Claude Bash Completion

Bash completion script for the Claude Code CLI, providing tab completion for built-in slash commands, CLI flags and subcommands, and custom commands and skills.

Features

• Auto-completion for all Claude Code built-in slash commands (123 commands)
• Auto-completion for CLI flags and their values (71 flags)
• Auto-completion for CLI subcommands (14 subcommands)
• Auto-completion for custom commands and skills from personal and project directories
• Filesystem fallback when no programmatic completion matches

Command, flag, and subcommand counts reflect Claude Code v2.1.211.

Requirements

• Bash shell
• Claude Code installed and configured
• bash-completion package (usually pre-installed on most systems)

Installation

Method 1: Source in .bashrc

1. Clone or download this repository:

git clone https://github.com/cldotdev/claude-bash-completion.git

2. Add the following line to your ~/.bashrc:

source /path/to/claude-bash-completion/claude-completion.bash

3. Reload your shell configuration:

source ~/.bashrc

Method 2: Install to system completion directory

Copy the script to your system's bash completion directory:

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

Then reload your shell or start a new terminal session.

Usage

Once installed, you can use tab completion with the claude command:

# Slash commands
claude /         # Shows all available slash commands
claude /con      # Completes to /config, /context, /cost, etc.

# CLI flags
claude --        # Shows all long flags
claude --mo      # Completes to --model

# Flag values
claude --model   # Shows model options: sonnet, opus, haiku, etc.
claude --effort  # Shows effort levels: low, medium, high, xhigh, max

# Subcommands
claude           # Shows subcommands: doctor, mcp, auth, etc.
claude up        # Completes to update, upgrade

# Custom commands and skills
claude /my-custom-    # If you have custom commands in ~/.claude/commands/

How It Works

Sourcing the script does two things:

1. Registers the completion function via complete -o default -F _claude_bash_completion claude, so pressing Tab after claude runs the completion logic. The -o default option falls back to filesystem completion when no programmatic match applies.

2. Defines a claude() shell wrapper that shadows the claude binary. When the command line contains a slash command, the wrapper merges the slash command and everything after it into a single argument before delegating to the real binary via command claude. This lets multi-word arguments reach the CLI intact:

   claude --model haiku /format 'some text'
   # runs: command claude --model haiku "/format some text"

Completions are drawn from static built-in lists (commands, flags, subcommands, and known flag values), dynamically discovered custom commands and skills (see Custom Commands and Skills), and a filesystem fallback when nothing else matches.

Custom Commands and Skills

The script automatically discovers custom slash commands and skills from these locations:

• Personal commands: ~/.claude/commands/*.md
• Personal skills: ~/.claude/skills/<name>/SKILL.md
• Project commands: <project-root>/.claude/commands/*.md
• Project skills: <project-root>/.claude/skills/<name>/SKILL.md

Subdirectory structures are converted to colon-separated names (e.g., commands/dev/rails.md or skills/dev/rails/SKILL.md becomes /dev:rails).

Project root is detected via git rev-parse --show-toplevel. Project-level discovery is skipped when not inside a git repository.

Development

Run the test suite with bats, and lint the script with shellcheck:

bats tests/
shellcheck claude-completion.bash

The built-in command, flag, and subcommand lists are aligned with each Claude Code release. See CLAUDE.md for the alignment procedure.

License

MIT License