diff --git a/src/build/bash_completions.zig b/src/build/bash_completions.zig
index e8b6a254c..06d42e70e 100644
--- a/src/build/bash_completions.zig
+++ b/src/build/bash_completions.zig
@@ -37,7 +37,6 @@ fn writeBashCompletions(writer: anytype) !void {
     const pad4 = pad3 ++ pad1;
 
     try writer.writeAll(
-        \\
         \\# -o nospace requires we add back a space when a completion is finished
         \\# and not part of a --key= completion
         \\addSpaces() {
@@ -281,6 +280,11 @@ fn writeBashCompletions(writer: anytype) !void {
         \\  cur=""; prev=""; prevWasEq=false; COMPREPLY=()
         \\  ghostty="$1"
         \\
+        \\  # script assumes default COMP_WORDBREAKS of roughly $' \t\n"\'><=;|&(:'
+        \\  # if = is missing this script will degrade to matching on keys only.
+        \\  # eg: --key=
+        \\  # this can be improved if needed see: https://github.com/ghostty-org/ghostty/discussions/2994
+        \\
         \\  if [ "$2" = "=" ]; then cur=""
         \\  else                    cur="$2"
         \\  fi