diff --git a/docs/config/README.md b/docs/config/README.md
index 5aaba98d1..36c9f8075 100644
--- a/docs/config/README.md
+++ b/docs/config/README.md
@@ -2528,7 +2528,7 @@ The default functionality is:
 
 *: This variable can only be used as a part of a style string
 
-### Example
+### Examples
 
 ```toml
 # ~/.config/starship.toml
@@ -2539,6 +2539,14 @@ number_threshold = 4
 symbol_threshold = 0
 ```
 
+#### Changing process grouping behavior in fish
+
+When using the Fish shell, Starship counts **job groups** instead of individual process IDs by default. This prevents overcounting when a pipeline has multiple processes but only one suspended group. To revert to the legacy PID-based counting, please add the following to your shell config:
+
+```fish
+set -g __starship_fish_use_job_groups "false"
+```
+
 ## Julia
 
 The `julia` module shows the currently installed version of [Julia](https://julialang.org/).
diff --git a/src/init/starship.fish b/src/init/starship.fish
index 1b65bfaae..011f757a5 100644
--- a/src/init/starship.fish
+++ b/src/init/starship.fish
@@ -1,3 +1,16 @@
+function __starship_set_job_count --description 'Set STARSHIP_JOBS using fish job groups (or legacy PIDs if toggled)'
+    # To force legacy behavior (process PIDs), set this variable to "false":
+    #   set -g __starship_fish_use_job_groups "false"
+    if test "$__starship_fish_use_job_groups" = "false"
+        # Legacy behavior: counts PIDs (may overcount pipelines with terminated producers)
+        set -l __count (jobs -p 2>/dev/null | count)
+    else
+        # Default behavior: count job groups
+        set -l __count (jobs -g 2>/dev/null | count)
+    end
+    set -g STARSHIP_JOBS $__count
+end
+
 function fish_prompt
     switch "$fish_key_bindings"
         case fish_hybrid_key_bindings fish_vi_key_bindings fish_helix_key_bindings
@@ -5,11 +18,14 @@ function fish_prompt
         case '*'
             set STARSHIP_KEYMAP insert
     end
+
     set STARSHIP_CMD_PIPESTATUS $pipestatus
     set STARSHIP_CMD_STATUS $status
     # Account for changes in variable name between v2.7 and v3.0
     set STARSHIP_DURATION "$CMD_DURATION$cmd_duration"
-    set STARSHIP_JOBS (count (jobs -p))
+
+    __starship_set_job_count
+
     if test "$TRANSIENT" = "1"
         set -g TRANSIENT 0
         # Clear from cursor to end of screen as `commandline -f repaint` does not do this
@@ -32,11 +48,15 @@ function fish_right_prompt
         case '*'
             set STARSHIP_KEYMAP insert
     end
+
     set STARSHIP_CMD_PIPESTATUS $pipestatus
     set STARSHIP_CMD_STATUS $status
     # Account for changes in variable name between v2.7 and v3.0
     set STARSHIP_DURATION "$CMD_DURATION$cmd_duration"
-    set STARSHIP_JOBS (count (jobs -p))
+
+    # Now it's safe to call job count function (after status capture)
+    __starship_set_job_count
+
     if test "$RIGHT_TRANSIENT" = "1"
         set -g RIGHT_TRANSIENT 0
         if type -q starship_transient_rprompt_func
@@ -88,4 +108,4 @@ end
 
 # Set up the session key that will be used to store logs
 # We don't use `random [min] [max]` because it is unavailable in older versions of fish shell
-set -gx STARSHIP_SESSION_KEY (string sub -s1 -l16 (random)(random)(random)(random)(random)0000000000000000)
+set -gx STARSHIP_SESSION_KEY (string sub -s1 -l16 (random)(random)(random)(random)(random)0000000000000000)
\ No newline at end of file