Claude Code Shell Completion

🇯🇵 日本語版はこちら

Shell completion scripts for Claude Code, providing tab completion for commands, subcommands, and options in bash, zsh, and Nushell.

Features

• Command completion: Tab complete claude subcommands (agents, auto-mode, auth, mcp, plugin, plugins, setup-token, doctor, update, upgrade, install)
• Option completion: All CLI options and flags are completable
• Contextual suggestions: Option values are suggested where applicable
  • Output formats: text, json, stream-json
  • Permission modes: acceptEdits, bypassPermissions, default, dontAsk, plan, auto
  • Models: sonnet, opus, haiku, etc.
  • Setting sources: user, project, local
  • Effort levels: low, medium, high, max
• File path completion: For options that expect file paths (e.g., --settings, --mcp-config, --add-dir, --file, --debug-file)
• Subcommand completion: Full subcommand trees for mcp and plugin commands

Quick Start

git clone https://github.com/hmmf022/cc-completion.git
cd cc-completion

Bash

mkdir -p ~/.local/share/bash-completion/completions
ln -sf "$(pwd)/claude-completion.bash" ~/.local/share/bash-completion/completions/claude
source ~/.local/share/bash-completion/completions/claude

Zsh

sudo ln -sf "$(pwd)/_claude" /usr/local/share/zsh/site-functions/_claude
autoload -Uz compinit && compinit

Nushell

Add to your Nushell config file ($nu.config-path):

use /path/to/cc-completion/claude-completions.nu *

For other installation methods (oh-my-zsh, system-wide bash, etc.), see Installation Details below.

Installation Details

Bash

Method 1: System-wide installation

Option A: Copy (simple)

sudo cp claude-completion.bash /etc/bash_completion.d/claude

Note: After updating the repository (e.g., git pull), you need to copy the file again.

Option B: Symbolic link (recommended)

sudo ln -sf "$(pwd)/claude-completion.bash" /etc/bash_completion.d/claude

Note: Updates are reflected automatically via git pull. Do not delete or move the cloned repository.

Then reload your shell or run:

source /etc/bash_completion.d/claude

Method 2: User-level installation

mkdir -p ~/.local/share/bash-completion/completions

Option A: Copy (simple)

cp claude-completion.bash ~/.local/share/bash-completion/completions/claude

Note: After updating the repository (e.g., git pull), you need to copy the file again.

Option B: Symbolic link (recommended)

ln -sf "$(pwd)/claude-completion.bash" ~/.local/share/bash-completion/completions/claude

Note: Updates are reflected automatically via git pull. Do not delete or move the cloned repository.

Add to your ~/.bashrc:

source ~/.local/share/bash-completion/completions/claude

Method 3: Manual sourcing

Add to your ~/.bashrc:

source /path/to/claude-completion.bash

Zsh

Method 1: System-wide installation

Option A: Copy (simple)

sudo cp _claude /usr/local/share/zsh/site-functions/_claude

Note: After updating the repository (e.g., git pull), you need to copy the file again.

Option B: Symbolic link (recommended)

sudo ln -sf "$(pwd)/_claude" /usr/local/share/zsh/site-functions/_claude

Note: Updates are reflected automatically via git pull. Do not delete or move the cloned repository.

Then reload completion:

rm -f ~/.zcompdump; compinit

Method 2: User-level installation with oh-my-zsh

mkdir -p ~/.oh-my-zsh/custom/plugins/claude

Option A: Copy (simple)

cp _claude ~/.oh-my-zsh/custom/plugins/claude/_claude

Note: After updating the repository (e.g., git pull), you need to copy the file again.

Option B: Symbolic link (recommended)

ln -sf "$(pwd)/_claude" ~/.oh-my-zsh/custom/plugins/claude/_claude

Note: Updates are reflected automatically via git pull. Do not delete or move the cloned repository.

Add to your ~/.zshrc:

plugins=(... claude)

Method 3: Manual fpath

Add to your ~/.zshrc before compinit:

fpath=(/path/to/cc-completion $fpath)
autoload -Uz compinit && compinit

Nushell

Add to your Nushell config file ($nu.config-path):

use /path/to/cc-completion/claude-completions.nu *

Note: Replace /path/to/cc-completion with the actual path to this cloned repository.

Usage Examples

After installation, you can use tab completion with the claude command:

# Complete subcommands
claude <TAB>
# Shows: agents auto-mode auth mcp plugin plugins setup-token doctor update upgrade install

# Complete options
claude --<TAB>
# Shows: --debug --verbose --print --model --help ...

# Complete option values
claude --output-format <TAB>
# Shows: text json stream-json

claude --permission-mode <TAB>
# Shows: acceptEdits bypassPermissions default dontAsk plan auto

claude --model <TAB>
# Shows: sonnet opus haiku best sonnet1m

claude --effort <TAB>
# Shows: low medium high max

# Complete install targets
claude install <TAB>
# Shows: stable latest --force --help

# Complete auth subcommands
claude auth <TAB>
# Shows: login logout status

# Complete auth login options
claude auth login --<TAB>
# Shows: --claudeai --console --email --sso --help

# Complete auth status options
claude auth status --<TAB>
# Shows: --json --text --help

# Complete mcp subcommands
claude mcp <TAB>
# Shows: add add-from-claude-desktop add-json get list remove reset-project-choices serve

# Complete mcp add options
claude mcp add --transport <TAB>
# Shows: stdio sse http

# Complete plugin subcommands
claude plugin <TAB>
# Shows: disable enable install list marketplace uninstall update validate

# File path completion
claude --settings <TAB>
# Shows files and directories

Supported Commands

• agents - List configured agents (with --setting-sources option)
• auto-mode - Inspect auto mode classifier configuration
  • config - Show auto mode classifier configuration
  • critique - Run auto mode critique on a conversation (with --model option)
  • defaults - Show default auto mode classifier configuration
• auth - Manage authentication
  • login - Sign in to your Anthropic account (with --claudeai, --console, --email, --sso options)
  • logout - Log out of your Anthropic account
  • status - Show current authentication status (with --json, --text options)
• mcp - Configure and manage MCP servers
  • add - Add an MCP server (with --scope, --transport, --env, --header, --callback-port, --client-id, --client-secret options)
  • add-from-claude-desktop - Import MCP servers from Claude Desktop (with --scope option)
  • add-json - Add an MCP server with a JSON string
  • get - Get details about an MCP server
  • list - List configured MCP servers
  • remove - Remove an MCP server (with --scope option)
  • reset-project-choices - Reset all approved and rejected project-scoped servers
  • serve - Start the Claude Code MCP server
• plugin - Manage Claude Code plugins
  • disable - Disable an enabled plugin
  • enable - Enable a disabled plugin
  • install (i) - Install a plugin from available marketplaces
  • list - List installed plugins
  • marketplace - Manage Claude Code marketplaces (add, list, remove (rm), update)
  • uninstall (remove) - Uninstall an installed plugin
  • update - Update a plugin to the latest version
  • validate - Validate a plugin or marketplace manifest
• setup-token - Set up a long-lived authentication token
• doctor - Check the health of your Claude Code auto-updater
• update - Check for updates and install if available
• plugins - Alias for plugin
• upgrade - Alias for update
• install - Install Claude Code native build (with --force option)

Supported Options

All Claude Code CLI options are supported, including:

• Session management: --continue, --resume, --fork-session, --from-pr
• Model selection: --model, --fallback-model
• Output control: --print, --output-format, --input-format
• Permissions: --permission-mode, --dangerously-skip-permissions
• Tools: --tools, --allowed-tools, --disallowed-tools
• MCP: --mcp-config, --strict-mcp-config
• File resources: --file
• Worktree: --worktree, --tmux
• Debugging: --debug, --debug-file
• And many more...

Testing

To verify the installation:

# For bash
type _claude_completion

# For zsh
which _claude

For Nushell, verify the completions are loaded:

# Check if the external command is registered
help commands | where name =~ "claude"

Try tab completion:

claude --mod<TAB>
# Should complete to: claude --model

Troubleshooting

Bash completion not working

1. Ensure bash-completion package is installed:

   # Ubuntu/Debian
   sudo apt-get install bash-completion
   
   # macOS (Homebrew)
   brew install bash-completion@2

2. Verify bash-completion is loaded in your shell:

   type _init_completion

Zsh completion not working

1. Ensure compinit is called in your ~/.zshrc:

   autoload -Uz compinit && compinit

2. Rebuild completion cache:

   rm -f ~/.zcompdump*; compinit

3. Verify the completion function is loaded:

   which _claude

Nushell completion not working

1. Ensure you are using Nushell 0.80 or later (required for extern completions):

   version

2. Check that the completions are registered:

   help commands | where name =~ "claude"

Contributing

If you find missing commands or options, please update the completion scripts:

• For bash: Edit claude-completion.bash
• For zsh: Edit _claude
• For Nushell: Edit claude-completions.nu

License

MIT