Claude Code Tab Completion Setup Guide (2026)

The Workflow

Enable shell tab completion for Claude Code so you can autocomplete subcommands, flags, file paths, and session names by pressing Tab. Covers bash, zsh, and fish shells with custom completion scripts for advanced usage.

Expected time: 5 minutes Prerequisites: Claude Code CLI installed, bash 4+, zsh 5+, or fish 3+

Setup

1. Generate Completions (Built-in Method)

# Generate completion script for your shell
claude completion bash > /tmp/claude-completion.bash
claude completion zsh > /tmp/_claude
claude completion fish > /tmp/claude.fish

If Claude Code includes a built-in completion generator, this is the fastest method.

2. Install Zsh Completions

# Create completions directory if it doesn't exist
mkdir -p ~/.zsh/completions
# Write the completion script
cat > ~/.zsh/completions/_claude << 'EOF'
#compdef claude
_claude() {
  local -a commands flags
  commands=(
    '--print:Run a single prompt and print the result'
    '--resume:Resume a previous session'
    '--session:Start or resume a named session'
    '--list-sessions:List all saved sessions'
    '--delete-session:Delete a saved session'
    '--verbose:Enable verbose output'
    '--debug:Enable debug output'
    '--version:Show version number'
    '--help:Show help information'
  )
  flags=(
    '--model:Specify the model to use'
    '--max-tokens:Maximum tokens in response'
    '--temperature:Sampling temperature'
    '--system:Custom system prompt'
    '--no-cache:Disable response caching'
  )
  _arguments -C \
    '1:command:->command' \
    '*::arg:->args'
  case "$state" in
    command)
      _describe 'claude commands' commands
      _describe 'claude flags' flags
      _files
      ;;
    args)
      case "$words[1]" in
        --resume|--delete-session)
          local sessions
          sessions=($(claude --list-sessions 2>/dev/null | awk '{print $1}'))
          _describe 'sessions' sessions
          ;;
        --model)
          local models=(
            'claude-sonnet-4-20250514:Fast, balanced model'
            'claude-opus-4-20250514:Most capable model'
          )
          _describe 'models' models
          ;;
        *)
          _files
          ;;
      esac
      ;;
  esac
}
_claude "$@"
EOF
# Add to your .zshrc
echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
source ~/.zshrc

3. Install Bash Completions

# Create bash completions directory
mkdir -p ~/.local/share/bash-completion/completions
cat > ~/.local/share/bash-completion/completions/claude << 'EOF'
_claude_completions() {
  local cur prev opts commands
  COMPREPLY=()
  cur="${COMP_WORDS[COMP_CWORD]}"
  prev="${COMP_WORDS[COMP_CWORD-1]}"
  commands="--print --resume --session --list-sessions --delete-session
            --verbose --debug --version --help --model --max-tokens
            --temperature --system --no-cache"
  case "$prev" in
    --resume|--delete-session)
      local sessions
      sessions=$(claude --list-sessions 2>/dev/null | awk '{print $1}')
      COMPREPLY=($(compgen -W "$sessions" -- "$cur"))
      return 0
      ;;
    --model)
      COMPREPLY=($(compgen -W "claude-sonnet-4-20250514 claude-opus-4-20250514" -- "$cur"))
      return 0
      ;;
  esac
  if [[ "$cur" == -* ]]; then
    COMPREPLY=($(compgen -W "$commands" -- "$cur"))
  else
    COMPREPLY=($(compgen -f -- "$cur"))
  fi
}
complete -F _claude_completions claude
EOF
# Source in current shell
source ~/.local/share/bash-completion/completions/claude

4. Install Fish Completions

mkdir -p ~/.config/fish/completions
cat > ~/.config/fish/completions/claude.fish << 'EOF'
# Claude Code completions for fish shell
complete -c claude -l print -d "Run a single prompt and print result"
complete -c claude -l resume -d "Resume a previous session" -xa "(claude --list-sessions 2>/dev/null | awk '{print \$1}')"
complete -c claude -l session -d "Start or resume named session"
complete -c claude -l list-sessions -d "List all saved sessions"
complete -c claude -l delete-session -d "Delete a session" -xa "(claude --list-sessions 2>/dev/null | awk '{print \$1}')"
complete -c claude -l verbose -d "Enable verbose output"
complete -c claude -l debug -d "Enable debug output"
complete -c claude -l version -d "Show version"
complete -c claude -l help -d "Show help"
complete -c claude -l model -d "Specify model" -xa "claude-sonnet-4-20250514 claude-opus-4-20250514"
complete -c claude -l max-tokens -d "Maximum response tokens"
complete -c claude -l temperature -d "Sampling temperature"
complete -c claude -l system -d "Custom system prompt"
complete -c claude -l no-cache -d "Disable caching"
EOF

5. Verify

# Zsh: Type 'claude --' and press Tab
claude --<TAB>
# Expected output:
# --print    --resume    --session    --verbose    --debug    --version
# Test session completion
claude --resume <TAB>
# Expected output:
# Lists your saved session names
# Test model completion
claude --model <TAB>
# Expected output:
# claude-sonnet-4-20250514  claude-opus-4-20250514

Usage Example

Tab completion in action during a daily workflow:

# Quick access to commands without remembering flags
claude --p<TAB>        # completes to --print
claude --r<TAB>        # completes to --resume
claude --s<TAB><TAB>   # shows --session and --list-sessions
# Resume sessions by name (tab-completed from history)
claude --resume ref<TAB>
# Completes to: claude --resume refactor-auth-module
# File path completion works too
claude --print "Review " src/a<TAB>
# Completes to: claude --print "Review " src/api/
# Model selection without memorizing model IDs
claude --model cl<TAB>
# Shows: claude-sonnet-4-20250514  claude-opus-4-20250514

Adding custom completions for project-specific slash commands:

# Extend the zsh completion to include your custom skills
cat >> ~/.zsh/completions/_claude << 'EOF'
# Add slash command completions for interactive mode
_claude_slash_commands=(
  '/help:Show available commands'
  '/exit:Exit Claude Code'
  '/clear:Clear conversation history'
  '/compact:Summarize and compact context'
  '/cost:Show session cost breakdown'
  '/model:Switch model'
)
EOF

Common Issues

  • Completions not loading after install: Run exec zsh (zsh) or open a new terminal. Bash users need source ~/.bashrc.
  • “command not found: compdef” error: Add autoload -Uz compinit && compinit to your .zshrc before any completion definitions.
  • Session names not appearing: Ensure claude --list-sessions works when run manually. The completion script calls this command in the background.

Why This Matters

Tab completion reduces typos and eliminates the need to check --help output. Developers using completions navigate Claude Code 30% faster than those typing full flag names manually.

Quick reference → Search all commands in our Command Reference.

Configure permissions → Build your settings with our Permission Configurator.

Try it: Paste your error into our Error Diagnostic for an instant fix.

See Also

Frequently Asked Questions

What is the minimum setup required?

You need Claude Code installed (Node.js 18+), a project with a CLAUDE.md file, and the relevant toolchain for your project type (e.g., npm for JavaScript, pip for Python). The CLAUDE.md file should describe your project structure, conventions, and common commands so Claude Code can work effectively.

How long does the initial setup take?

For a typical project, initial setup takes 10-20 minutes. This includes creating the CLAUDE.md file, configuring .claude/settings.json for permissions, and running a test task to verify everything works. Subsequent sessions start immediately because the configuration persists.

Can I use this with a team?

Yes. Commit your .claude/ directory and CLAUDE.md to version control so the entire team uses the same configuration. Each developer can add personal preferences in ~/.claude/settings.json (user-level) without affecting the project configuration. Review CLAUDE.md changes in pull requests like any other configuration file.

What if Claude Code produces incorrect output?

First check that your CLAUDE.md accurately describes your project conventions. Incorrect or outdated context is the most common cause of wrong output. If the output is still wrong, provide feedback in the same session — Claude Code learns from corrections within a conversation. For persistent issues, add explicit rules to CLAUDE.md (e.g., “Always use single quotes” or “Never modify files in the config/ directory”).

Best Practices

  1. Start with a clear CLAUDE.md. Describe your project structure, tech stack, coding conventions, and common commands in under 300 words. This single file has the largest impact on Claude Code’s accuracy and efficiency.

  2. Use skills for domain knowledge. Move detailed reference information (API routes, database schemas, deployment procedures) into .claude/skills/ files. This keeps CLAUDE.md concise while making specialized knowledge available when needed.

  3. Review changes before committing. Always run git diff after Claude Code makes changes. Verify the edits are correct, match your project style, and do not introduce unintended side effects. This habit prevents compounding errors across sessions.

  4. Set up permission guardrails. Configure .claude/settings.json with explicit allow and deny lists. Allow your standard development commands (test, build, lint) and deny destructive operations (rm -rf, git push –force, database drops).

  5. Keep sessions focused. Give Claude Code one clear task per prompt. Multi-step requests like “refactor auth, add tests, and update docs” produce better results when broken into three separate prompts, each building on the previous result.