Claude Codeのadd-dirをfzf・ghqと組み合わせて使う

Tips
2026.05.06

はじめに

マイクロサービス構成のプロジェクトを開発していると、「APIゲートウェイの実装を確認しながら、認証サービス側にも修正を加えたい」という場面がよく出てきます。 また、ライブラリを試す際に作成したサンプルリポジトリを参照しながら、本番コードを書きたいケースも少なくありません。

Claude Codeにはadd-dirという機能があり、現在開いているプロジェクト以外のディレクトリをコンテキストに追加できます。 以前は claude --add-dir のパスをシェルの補完に頼りながら毎回手打ちしていましたが、リポジトリ数が増えるにつれてタイポや入力ミスが重なり、実際には使わなくなっていました。 そこでリポジトリ管理ツールのghqとファジーファインダーのfzfを組み合わせることで、参照したいリポジトリをインタラクティブに選択してClaude Codeへ渡せるようにしました。 本記事では、この三つを組み合わせた便利なシェル関数の作り方を紹介します。

使用するツールの概要

add-dir とは

add-dirはClaude Codeの機能で、メインのプロジェクトディレクトリに加えて、任意のディレクトリをClaude Codeのコンテキストに追加します。 追加されたディレクトリのコードをClaude Codeが参照できるようになるため、複数リポジトリをまたいだ質問や修正を依頼できます。

CLIフラグとして --add-dir を使う方法と、Claude Codeのインタラクティブセッション内で /add-dir スラッシュコマンドを使う方法の二通りがあります。 起動前に参照先が決まっているなら --add-dir、作業途中で追加したくなった場合は /add-dir と使い分けるとスムーズです。

ghq とは

ghqはリポジトリをルールに基づいた統一的なディレクトリ構造で管理するツールです。 ghq get <URL> でcloneすると $GOPATH/src 以下（または ghq.root で指定したパス）にホスト名・オーナー名・リポジトリ名の階層で保存されます。 ghq list でローカルに存在するリポジトリの一覧を取得できます。

find コマンドや ls でも代替できますが、ghq は全リポジトリが一か所に集まることが前提のため ghq list --full-path の1コマンドで全件のフルパスを取得できます。 リポジトリ数が多い環境では特に差が出ます。 開発を行うディレクトリを決めている場合は ls などで代替しても問題ありません。

fzf とは

fzfはコマンドラインで動作するファジーファインダーです。 標準入力に渡したリストをインタラクティブにあいまい検索で絞り込め、-m（--multi）オプションで複数選択にも対応しています。

使用環境

ツール 確認バージョン
Claude Code v2.1.126
ghq 1.x
fzf 0.67.x
シェル zsh / bash

セットアップ

インストール

各ツールが未導入の場合はインストールします。

# ghq（Homebrewの場合）
brew install ghq

# fzf（Homebrewの場合）
brew install fzf

# Claude Code
npm install -g @anthropic-ai/claude-code

Linuxの場合はそれぞれのパッケージマネージャーや公式インストールスクリプトを利用してください。

ghq でリポジトリを管理する

まずは ghq でリポジトリをcloneしておきます。

# GitHubからclone
ghq get github.com/your-org/api-gateway
ghq get github.com/your-org/auth-service
ghq get github.com/your-org/user-service

# ローカルのリポジトリ一覧を確認する
ghq list

出力例：

github.com/your-org/api-gateway
github.com/your-org/auth-service
github.com/your-org/user-service

ghq list --full-path でフルパスを取得できます。

ghq list --full-path

出力例：

/home/user/ghq/github.com/your-org/api-gateway
/home/user/ghq/github.com/your-org/auth-service
/home/user/ghq/github.com/your-org/user-service

fzf・ghq と組み合わせたシェル関数

単一のリポジトリを選択して起動する

最もシンプルな組み合わせです。 ghq list --full-path の出力を fzf に渡してリポジトリを一つ選択し、--add-dir フラグでClaude Codeに渡します。

function claude-with-repo() {
  local dir
  dir=$(ghq list --full-path | fzf --prompt="参照リポジトリを選択: ")
  # 選択がキャンセルされた場合は何もしない
  [[ -z "$dir" ]] && return
  claude --add-dir "$dir"
}

~/.zshrc（または~/.bashrc）に追記してシェルを再起動すると、claude-with-repo コマンドとして使えるようになります。

複数のリポジトリを選択して起動する

マイクロサービス開発など、複数のリポジトリを同時に参照したい場合は fzf の -m オプションで複数選択できます。 Tab キーで複数のリポジトリをマークし、Enter で確定します。

function claude-with-repos() {
  local selected
  selected=$(ghq list --full-path | fzf -m --prompt="参照リポジトリを選択（Tab: 複数選択）: ")
  [[ -z "$selected" ]] && return

  # 選択されたパスを --add-dir フラグとして配列に積む
  local args=()
  while IFS= read -r dir; do
    args+=(--add-dir "$dir")
  done <<< "$selected"

  claude "${args[@]}"
}

この関数を実行すると fzf のインタラクティブな選択画面が表示され、Tab キーでリポジトリを複数マークして Enter で確定すると、選択したすべてのリポジトリのコードをコンテキストに加えた状態で Claude Code が起動します。

既存セッションに追加する（/add-dir スラッシュコマンド）

Claude Codeのインタラクティブセッション中に追加で参照先を増やしたい場合は、/add-dir スラッシュコマンドが使えます。

/add-dir /home/user/ghq/github.com/your-org/auth-service

追加したディレクトリは /permissions コマンドで確認できます。 /permissions を実行後、タブを Workspace に切り替えると、現在のセッションで許可されているディレクトリの一覧が表示されるため、意図したリポジトリが正しく追加されているかを確認するときに役立ちます。

別ターミナルで ghq list --full-path | fzf を実行してパスをコピーし、セッション内に貼り付けると手間が少なくなります。

セッション内でパスを素早く取得するためのエイリアスを用意しておくと便利です。

# ghq + fzf でパスをクリップボードにコピーするエイリアス
alias ghq-fzf-copy='ghq list --full-path | fzf | pbcopy'
# Linux（xclipやwl-copyを使う場合）
alias ghq-fzf-copy='ghq list --full-path | fzf | xclip -selection clipboard'

また、tmux や zellij などのターミナルマルチプレクサを使っている場合は、フローティングウィンドウなどを活用してディレクトリ選択の支援ができます。 こちらはまた別の機会に紹介したいと思います。

実際の使い方：マイクロサービス開発の例

たとえば、api-gateway を作業対象のプロジェクトとして開きながら、auth-service と user-service のコードも参照したい場合は以下のように操作します。

# 作業ディレクトリに移動する
cd ~/ghq/github.com/your-org/api-gateway

# claude-with-repos を起動し、fzf で auth-service と user-service を選択する
claude-with-repos

fzf の画面でリポジトリをTab キーで選択します。

> github.com/your-org/auth-service    <- Tab でマーク
  github.com/your-org/user-service   <- Tab でマーク
  github.com/your-org/api-gateway

Enter で確定すると、以下のコマンドと同等の状態でClaude Codeが起動します。

claude \
  --add-dir /home/user/ghq/github.com/your-org/auth-service \
  --add-dir /home/user/ghq/github.com/your-org/user-service

これにより、Claude Codeに「api-gateway のエンドポイント定義に合わせて、auth-service のトークン検証ロジックを確認して」のような、複数リポジトリをまたいだ依頼がそのまま投げられます。

実際の使い方：サンプルコードを参照しながら開発する例

新しいライブラリを試したサンプルリポジトリを参照しながら、本番リポジトリに実装を取り込む場合も同様に使えます。

# 本番リポジトリで作業を開始する
cd ~/ghq/github.com/your-org/production-app

# fzf でサンプルリポジトリを選んで追加する
claude-with-repo

fzf でサンプルリポジトリを選択して起動後、「サンプルコードの実装パターンを参考に、本番コードへ組み込んで」と依頼するだけです。 ライブラリのサンプルコードとプロダクションコードを往復する必要がなくなります。

まとめ

Claude Codeのadd-dirをghqとfzfと組み合わせることで、複数リポジトリへのコンテキスト追加をインタラクティブかつ素早く行えるようになります。 実際に運用してみると、--add-dir のパス入力に費やしていた手間がほぼゼロになり、「参照先を追加する」という操作の心理的ハードルが下がったことで、Claude Codeへの依頼の粒度が細かくなった実感があります。 最近の生成AI事情としてなるべくトークン消費を抑えるために、必要なコードだけをコンテキストに加える運用が増えているため、参照先の追加が手軽になったのは大きいです。マイクロサービス開発やサンプルコード参照など、複数リポジトリをまたいだ作業でぜひ試してみてください。 また、fzfには --preview オプションもあるので、今後は選択画面でリポジトリの内容をプレビューできるようにするなど、さらに便利な機能を追加してみたいと思います。

Claude Code のセッション内からもインタラクティブにリポジトリを選択して追加したい場合は、Claude CodeのCLIからghq+fzfでリポジトリを選択する（tmux / zellij対応）もあわせてご覧ください。

コメント

タイトルとURLをコピーしました