🚀
Claude Code CLIのzsh補完

2025/12/13に公開
テーマ「2025年の最も大きなチャレンジ」
 はじめにClaude Code CLIを使っていて、コマンドやオプションを覚えるのが大変だったので、zshの補完スクリプトを実装しました。120以上の言語に対応させています。

 使用例# コマンドの補完
claude <TAB>
# → mcp, plugin, agents, auth, auto-mode, gateway, project, ultrareview など

# オプションは前方一致で絞り込み
claude --allow<TAB>
# → --allow-dangerously-skip-permissions, --allowed-tools, --allowedTools

# 値を持つオプションはその値も補完
claude --permission-mode <TAB>
# → acceptEdits, auto, bypassPermissions, manual, dontAsk, plan

# MCPサーバーの削除時に動的補完
claude mcp remove <TAB>
# → 実際に設定されているサーバー名が表示される

# セッションの再開時に動的補完
claude --resume <TAB>
# → 利用可能なセッションIDが表示される

# エージェントとモデルも動的補完
claude --agent <TAB>
# → ~/.claude/agents などに定義したエージェント名
claude --model <TAB>
# → default, fable, opus, sonnet, haiku と設定済みのモデル名

 GitHubリポジトリhttps://github.com/1160054/claude-code-zsh-completion

 インストール方法
 Homebrewbrew tap 1160054/claude https://github.com/1160054/claude-code-zsh-completion
brew trust 1160054/claude
brew install claude-code-zsh-completion
Homebrew 6はサードパーティのtapを信頼するまで読み込まないので、真ん中の1行が要ります。
brew shellenvがHomebrewのsite-functionsをfpathに入れてくれるため、~/.zshrcの編集は不要です。brew upgradeで更新も追従します。
120以上のロケールファイルも一緒に入るので、日本語版に切り替えるときはリンクを張り替えるだけです。
ln -sf "$(brew --prefix)/share/claude-code-zsh-completion/completions/_claude.ja" \
  "$(brew --prefix)/share/zsh/site-functions/_claude"

 手動インストール# 英語版
mkdir -p ~/.zsh/completions && curl -o ~/.zsh/completions/_claude \
  https://raw.githubusercontent.com/1160054/claude-code-zsh-completion/main/completions/_claude

# 日本語版
mkdir -p ~/.zsh/completions && curl -o ~/.zsh/completions/_claude \
  https://raw.githubusercontent.com/1160054/claude-code-zsh-completion/main/completions/_claude.ja
~/.zshrcに以下を追加:
fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit
compinit
Oh My Zsh・zinit・antigen・sheldonにも対応しています。

 主な機能全てのclaudeコマンドの補完
MCPサーバー、プラグイン、セッションID、エージェント、モデルの動的補完
120以上の言語サポート（日本語、英語、中国語、スペイン語、フランス語、ドイツ語、韓国語など）
コンテキストを考慮した引数の提案

 実装の工夫
 動的補完MCPサーバーやセッション、エージェントの一覧は、設定ファイルやディレクトリを直接読んで候補にしています。jqなどの外部依存を増やしたくなかったので、grepとsedだけで処理しています。
# エージェントの動的補完
_claude_agent_names() {
  local -a agents
  local agent_dir agent_file name

  # ユーザーレベルとプロジェクトレベルの定義を見る
  for agent_dir in ~/.claude/agents ~/.config/claude/agents .claude/agents; do
    [[ -d "$agent_dir" ]] || continue

    for agent_file in ${agent_dir}/*.md(N); do
      # front matterのname:を優先し、なければファイル名
      name=$(sed -n '1,10{s/^name:[[:space:]]*\([^[:space:]]*\).*/\1/p;}' "$agent_file" 2>/dev/null | head -1)
      agents+=(${name:-${agent_file:t:r}})
    done
  done

  agents=(${(u)agents})

  compadd -a agents
}
実際に設定されているMCPサーバーやインストール済みのプラグイン、定義したエージェントが候補として表示されます。

 関数名の衝突に注意--agentの補完関数は、最初 _claude_agents という名前にしていました。ところがこの名前は claude agents コマンド用の補完関数として既にファイル内にあって、後から定義されたほうで上書きされます。--agent が何も補完しない状態になっていたのですが、エラーは出ないので気付きにくいところでした。
いまは _claude_agent_names にリネームした上で、同じ関数を二重定義していないかをテストで見るようにしています。

 CLIの変更に追従する手で書いている補完なので、CLI側にコマンドやオプションが増えるとズレます。実際、6個のトップレベルコマンドと20個以上のオプションをまとめて後追いするハメになりました。
そこで claude --help の出力と補完ファイルを突き合わせるチェックを毎週動かして、ズレていたらIssueを自動で立てるようにしました。push時とPR時だけだと、誰もpushしない間にCLIが更新されるケースを取りこぼします。

 多言語対応120以上の言語に対応しており、説明文を各言語に翻訳したファイルが用意されています。補完の構造は同じで、説明文のみを変更することで、各言語のユーザーが理解しやすい補完を実現しています。
構造が揃っていることはテストで見ていて、全120ファイルに構文チェック・必須関数の有無・オプション数の一致などをかけています（現在1565テスト）。

 まとめClaude Code CLIを日常的に使う場合、コマンドやIDを覚える必要がなくなります。動的補完により、実際に設定されているサーバー名やセッションID、エージェント名が表示されるので便利です。

 リンクGitHub: https://github.com/1160054/claude-code-zsh-completion
Claude Code Documentation: https://docs.claude.com/
はじめに

使用例

GitHubリポジトリ

インストール方法

Homebrew

手動インストール

主な機能

実装の工夫

動的補完

関数名の衝突に注意

CLIの変更に追従する

多言語対応

まとめ

リンク

Discussion
