bash-completion-for-claude

Tab completion for the claude CLI (Claude Code) in bash, zsh, and fish.

Claude Code ships no built-in completion generator (the client is closed-source, so source <(claude completion bash) is not possible). Static flag lists go stale on every release. These scripts instead parse claude --help at runtime and cache the result per version, so completion always matches the claude you actually have installed.

Install

git clone https://github.com/AzarAI-TOP/bash-completion-for-claude.git
cd bash-completion-for-claude
./install.sh

By default install.sh detects your current shell (from $SHELL) and installs just that one:

./install.sh          # detect current shell and install it
./install.sh bash     # install for a specific shell
./install.sh zsh
./install.sh fish
./install.sh all      # install for all three

If the detected shell is not one of bash/zsh/fish, it tells you and exits; install explicitly with one of the arguments above.

Then, in a new shell:

claude --<Tab>      # options:     --model --resume --print ...
claude <Tab>        # subcommands: agents auth mcp plugin update ...

Install locations:

shell	installed to	loading
bash	${XDG_DATA_HOME:-~/.local/share}/bash-completion/completions/claude	lazy-loaded by bash-completion; no ~/.bashrc edit
zsh	${XDG_DATA_HOME:-~/.local/share}/zsh/site-functions/_claude	autoloaded via compinit if the dir is on $fpath
fish	${XDG_CONFIG_HOME:-~/.config}/fish/completions/claude.fish	autoloaded by fish on demand

For zsh, the install dir must be on $fpath before compinit. If completion does not show up, add to ~/.zshrc:

fpath=("${XDG_DATA_HOME:-$HOME/.local/share}/zsh/site-functions" $fpath)
autoload -U compinit && compinit

How it works

• On first completion the script runs claude --help, extracts every --option and every subcommand from the Commands: section, and caches the list under ${XDG_CACHE_HOME:-~/.cache}/claude-completion/words-<version>.
• Later completions read the cache (instant). After you upgrade Claude Code the version changes, so a fresh list is generated automatically.
• A few path-taking options (--add-dir, --settings, --mcp-config, --debug-file, --system-prompt-file, --append-system-prompt-file) fall back to file/dir completion.

Requirements

• bash: bash-completion (provides the lazy-load dir and _init_completion / _filedir)
• zsh: compinit enabled (standard)
• fish: any recent version
• claude on PATH

Uninstall

rm -f "${XDG_DATA_HOME:-$HOME/.local/share}/bash-completion/completions/claude"
rm -f "${XDG_DATA_HOME:-$HOME/.local/share}/zsh/site-functions/_claude"
rm -f "${XDG_CONFIG_HOME:-$HOME/.config}/fish/completions/claude.fish"
rm -rf "${XDG_CACHE_HOME:-$HOME/.cache}/claude-completion"

License

MIT