Fish shell

1 Installing

• Ubuntu users can install an updated fish PPA.
• or, on macOS/Linux: install using homebrew

gararine reports how to make fish the default shell with homebrew:

# check the fish path with `which fish`. In the examples below it was located at: `/opt/homebrew/bin/fish`.
# Add fish to the known shells
sudo sh -c `which fish` >> /etc/shells
# Set fish as the default shell
chsh -s `which fish`
# Add brew binaries in fish path
fish_add_path /opt/homebrew/bin
#To collect command completions for all commands run:
fish_update_completions

2 Configuration

fish_add_path /usr/local/bin

set -gx PATH /usr/local/bin $PATH

set -U fish_user_paths /usr/local/bin $fish_user_paths

set -gx PATH (string match -v /usr/local/bin $PATH)

echo /opt/whatever/bin | sudo tee /etc/paths.d/whatever

fish_config

eval (ssh-agent -c)

wget https://gitlab.com/kyb/fish_ssh_agent/raw/master/functions/fish_ssh_agent.fish -P ~/.config/fish/functions/

fish_ssh_agent

wget https://github.com/ivakyb/fish_ssh_agent/raw/e09c21501c20730634ab80d6bc9329335eabe065/functions/fish_ssh_agent.fish -P ~/.config/fish/functions/

3 Plugins

We can hack fish. There are also popular plugin managers. As far as I can tell, a passable default is oh my fish

curl -L https://get.oh-my.fish | fish

Is fisher around too?

curl -sL https://git.io/fisher | source && fisher install jorgebucaran/fisher

It also handles omf plugins, apparently. The omf manual is brusque. See a helpful blog post. I’m currently running omf, but since it intrusively changed my prompt I’m grumpy about it. I switched to a better prompt, spacefish.

omf install spacefish

We do need the wacky powerline fonts.

sudo apt-get install fonts-powerline

There are various useful plugins that aren’t purely cosmetic. For example, fzf adds fuzzy history search. z does recency/frequency-based directory navigation.

4 Homebrew compatibility on Ubuntu

I use fish as my default shell, but Ubuntu automatically executes the bash startup script .profile on login. When I used homebrew, I ran into the following errors because it tried to run the fish init in a bash process:

bash: set: -g: invalid option
set: usage: set [-abefhkmnptuvxBCHP] [-o option-name] [--] [arg ...]
bash: set: -g: invalid option
...

This may be related to an intermittently reported bug in homebrew. The fix that worked for me was to change the automatically added line in .profile to:

eval $(SHELL=bash /bin/brew shellenv)

and to add

eval (env SHELL=fish /bin/brew shellenv)

to ~/.config/fish/config.fish.

5 Python environments

~/miniconda3/bin/conda init fish

source ~/miniconda3/etc/fish/conf.d/conda.fish

6 Vars, expansions, extensions, suffixes

Wildcards are minimal: just *, **, brace expansion and mv a.{txt,html.

For more sophisticated string processing, we can define custom functions (which I never actually do) or use classic subcommands, which I do all the time. Usually, I want to rename files:

for file in (ls *.html)
  mv $file (basename $file .html).txt
end

or expansion via string, which is harder to remember.

for file in (ls *.html)
  mv $file (string replace -r "\.html\$" .txt $file)
end

Or use another fancy utility like rename.

7 Loops

while true
  echo "Loop forever"
end
for var in list
    command $var
end

8 Test exit status

Similar to Bash.

if test $status -eq 0
  echo yeah
end

To simply execute the second command if the first succeeds, the command we want is and, which is hard to google for:

../bin/something.sh foo; and cp foo ~/Dropbox/

9 Temporary variable setting: uses env

env FOO=BAR baz.sh

10 VS Code

VS Code requires launching it from the command line if we use fish on macOS.

11 Aliases, custom commands

Command, alias or abbr — which should we use?

• Command lets us overwrite a command.
• Alias creates an alias, but lacks autocomplete.
• Abbr creates a kind of alias that expands and supports autocomplete.

12 Writing functions

• How do I set a default value for a named function argument?
• Parse options passed to a fish script or function
• How do I reference a variable in fish shell with a default fallback?
• Create a function

13 Gotchas

“Sophisticated” backgrounding, i.e. anything other than single shell commands, isn’t supported in fish. Background jobs aren’t in the background. Specifically, functions and piped commands don’t work.

Workaround:

function bgFunc
  fish -c (string join -- ' ' (string escape -- $argv)) &
end

14 Coding agents and $SHELL

Fish is a pleasant login shell for humans, but machines find it challenging and are usually set up to use different shells. Claude Code hard-codes bash and/or zsh. In particular, it ignores $SHELL if $SHELL is fish and falls back to zsh.

The problem is that the agent still believes it is using fish shell and all kinds of hijinks follow when it tries to use fish syntax. One fix is to update ~/.claude/CLAUDE.md — to say

the Bash tool runs zsh -l -c, disregard the environment block

That is the whole fix, which surprised me, because I had expected $PATH to be broken too. zsh -l -c is a login shell but not an interactive one, so it reads ~/.zshenv, ~/.zprofile and ~/.zlogin, but not ~/.zshrc, and no fish config at any point. Wiping the environment shows how little it knows unaided:

env -i HOME=$HOME /opt/homebrew/bin/fish -ilc 'for p in $PATH; echo $p; end'
env -i HOME=$HOME /bin/zsh -ilc 'print -l $path'

Fish reports /opt/homebrew/bin, ~/.pyenv/shims, ~/.local/bin and ~/bin. Zsh reports none of them, so by rights the agent should not be able to find uv. It finds uv anyway.

The desktop app is not the explanation: its own PATH is the bare /usr/bin:/bin:/usr/sbin:/sbin that it gets from launchd. Yet the shell Claude Code executes in has my whole config.fish ordering, including ~/.pyenv/shims, which config.fish only adds under status --is-interactive. So Claude Code harvests $PATH by running my interactive fish, and then declines to run any of my commands in it. It trusts fish enough to ask what my environment is, but not enough to use it.

So there is nothing to fix, only somewhere to look first should uv ever go missing. It does feel flaky as hell to rest on an undocumented harvesting step. If it breaks in the future I will need to arse around with .zprofile and .zshrc and typeset -U and suchlike.

15 Python environments

In lazy mode, python environments manipulates paths and environment variables. We need extra configuration in the fish shell. pyenv needs

set -x PYENV_ROOT $HOME/.pyenv
set -x PATH $PYENV_ROOT/bin $PATH
status --is-interactive; and pyenv init --path | source
status --is-interactive; and pyenv init - | source

See also How to use nvm, rbenv, pyenv, goenv… with the fish shell.

Or ditch pyenv and use uv.

16 Incoming

Deleting history interactively:

history delete

Native parallelism?:

while true
    if test (count (jobs)) -lt 5
        dostuff &
    else
        wait # to wait for _any_ job
    end
end

NB: it only allocates five jobs at a time. Nifty.