fish-helper

What this skill does

# Fish Shell Helper Agent

## What's New in Fish 4.x (2025-2026)

### Fish 4.0 (February 2025)

- **Rust rewrite**: Entire codebase ported from C++ to Rust (2,731 commits, 200+ contributors)
- **New keyboard protocol**: Human-readable bind notation (`bind ctrl-right` instead of escape sequences), xterm modifyOtherKeys and kitty keyboard protocol support
- **OSC 133 prompt marking**: Prompts and command output marked for terminal integration
- **Command-specific abbreviations**: `abbr --command git co checkout`
- **Self-installable builds**: Static binaries embed functions, man pages, and webconfig
- **History filtering**: `fish_should_add_to_history` function for selective exclusion
- **`string match --max-matches`** and **`set --no-event`** flags

### Fish 4.1 (September 2025)

- **Brace compound commands**: `{ echo 1; echo 2 }` syntax
- **Transient prompts**: `fish_transient_prompt` function for simplified prompt after execution
- **Mouse support**: OSC 133 prompt marking with kitty click events
- **`string pad --center`** option
- **Vi mode**: ctrl+a (increment) and ctrl+x (decrement)

### Fish 4.2 (November 2025)

- Multi-line autosuggestions from history
- `fish_tab_title` function for separate tab titles
- Fish assumes UTF-8 regardless of system locale

### Fish 4.3 (December 2025)

- **Universal variables replaced with global defaults** for cleaner configuration
- **Adaptive themes**: `[light]` and `[dark]` sections in theme files
- Terminal working directory reported via OSC 7

### Fish 4.4 (February 2026)

- Vi mode word motions aligned with Vim behavior (counts supported: `d3w`)
- New `catppuccin-*` color themes
- `set_color` strikethrough modifier

## Overview

Fish (Friendly Interactive SHell) is a modern interactive shell focused on user experience. It provides syntax highlighting, autosuggestions, and tab completions out of the box. Fish intentionally breaks POSIX compatibility in favor of cleaner, more discoverable syntax.

Key design principles:

- Discoverability over tradition (no hidden configuration)
- User-friendliness over backward compatibility
- Correctness (no word splitting on variables)

## Syntax Differences from Bash

### Variable Assignment

```fish
# Fish uses set, not VAR=value
set name "world"
set -gx PATH /usr/local/bin $PATH    # global + exported
set -l local_var "temporary"           # local scope
set -U EDITOR vim                      # universal (persists across sessions)
set -e var_name                        # erase variable
```

### Variable Scopes

- **Universal** (`-U`): Shared across all sessions, persisted to disk
- **Global** (`-g`): Current session only
- **Function** (`-f`): Current function
- **Local** (`-l`): Current block

### Command Substitution

```fish
# Fish uses (command) or $(command), NOT backticks
set files (ls)
echo "Current dir: $(pwd)"

# Output splits on newlines only (not whitespace like bash)
# Use quotes to prevent splitting
set content "$(cat file.txt)"
```

### No Process Substitution

```fish
# Bash: diff <(cmd1) <(cmd2)
# Fish: use psub
diff (cmd1 | psub) (cmd2 | psub)
```

### Conditionals and Loops

```fish
# if/else if/else/end (no then/fi)
if test -f /etc/os-release
    cat /etc/os-release
else if test -f /etc/issue
    cat /etc/issue
else
    echo "Unknown OS"
end

# switch/case/end (no esac, no fallthrough)
switch (uname)
case Linux
    echo "Linux"
case Darwin
    echo "macOS"
case '*'
    echo "Other"
end

# for/end (no do/done)
for file in *.txt
    echo $file
end

# while/end
while read -l line
    echo "Line: $line"
end < input.txt
```

### Lists (Arrays)

```fish
# All variables are lists. 1-indexed, negative indexing supported
set colors red green blue
echo $colors[1]        # red
echo $colors[-1]       # blue
echo $colors[2..3]     # green blue
echo (count $colors)   # 3

# PATH variables auto-split on colons
set -gx PATH /usr/local/bin /usr/bin /bin
```

### String Manipulation

```fish
# Use the string builtin (no ${var%pattern} parameter expansion)
string length "hello"                    # 5
string upper "hello"                     # HELLO
string replace "old" "new" "old text"    # new text
string split "," "a,b,c"                 # a\nb\nc
string match -r '(\d+)' "file42.txt"    # 42
string trim "  hello  "                  # hello
string sub -s 2 -l 3 "hello"            # ell
```

### Arithmetic

```fish
# Use math builtin (no $(( )) or let)
math 2 + 2                # 4
math "10 / 3"             # 3.333333 (floating point by default)
math "sqrt(16)"           # 4
set result (math "$x * 2")
```

### Special Variables

| Bash       | Fish                |
| ---------- | ------------------- |
| `$?`       | `$status`           |
| `$@`, `$*` | `$argv`             |
| `$$`       | `$fish_pid`         |
| `$#`       | `(count $argv)`     |
| `$!`       | `$last_pid`         |
| `$0`       | `(status filename)` |

### Other Key Differences

- No heredocs: use `printf '%s\n' "line1" "line2"` or multi-line strings
- No `[[`: use `test` or `[` only
- No subshells: use `begin; end` for grouping, `set -l` for scoping
- No `export`: use `set -gx`
- No `source ~/.bashrc`: use `source ~/.config/fish/config.fish`
- Globs that match nothing cause command failure (not literal pass-through)
- `?` glob deprecated; use `*` or disable with `qmark-noglob`
- No word splitting on variable expansion (a feature, not a bug)

## Functions Quick Reference

```fish
# Define a function
function greet -d "Greet someone"
    echo "Hello, $argv[1]!"
end

# Function with argument names
function mkcd -a dir -d "Create and enter directory"
    mkdir -p $dir && cd $dir
end

# Function wrapping a command (inherit completions)
function ls --wraps ls -d "ls with color"
    command ls --color=auto $argv
end

# Event handlers
function on_pwd_change --on-variable PWD
    echo "Changed to $PWD"
end

function on_exit --on-event fish_exit
    echo "Goodbye!"
end

# Save function to autoload file
funcsave greet   # saves to ~/.config/fish/functions/greet.fish
```

## Abbreviations Quick Reference

```fish
# Simple abbreviation
abbr -a gco git checkout
abbr -a gst git status

# Position: expand anywhere (not just as command)
abbr -a --position anywhere -- -C --color

# Command-specific (Fish 4.0+)
abbr --command git co checkout
abbr --command git br branch

# With cursor positioning
abbr -a L --position anywhere --set-cursor "| less"

# Function-based expansion
abbr -a !! --position anywhere --function last_history_item

# Regex-based
abbr -a dotenv --regex '\.env.*' --function edit_with_caution
```

## Completions Quick Reference

```fish
# Basic completion for a command
complete -c mycommand -s h -l help -d "Show help"
complete -c mycommand -s v -l verbose -d "Verbose output"

# Require a parameter
complete -c mycommand -s o -l output -r -d "Output file" -F

# Exclusive (require param, no files)
complete -c mycommand -s f -l format -x -a "json yaml toml" -d "Output format"

# Conditional completions
complete -c git -n "__fish_use_subcommand" -a checkout -d "Switch branches"
complete -c git -n "__fish_seen_subcommand_from checkout" -a "(git branch --format='%(refname:short)')" -d "Branch"

# Disable file completions globally
complete -c mycommand -f

# Wrap another command's completions
complete -c hub -w git
```

## Configuration Structure

```
~/.config/fish/
  config.fish              # Main config (runs on every shell start)
  conf.d/                  # Modular config snippets (sourced alphabetically)
    abbr.fish
    path.fish
    env.fish
  functions/               # Autoloaded functions (one per file)
    fish_prompt.fish
    fish_right_prompt.fish
    mkcd.fish
  completions/             # Custom completions (one per command)
    mycommand.fish
  themes/                  # Color themes (.theme files)
  fish_plugins             # Fisher plugin list
  fish_variables           # Universal variables (auto-managed, do not edit)
```

### Startup Order

1. Files in `conf.d/` directories (system, then