Claude Code・Codexでgit worktreeを使う実践ガイド

git worktreeで、Claude CodeやCodexを別ブランチで同時に衝突なく動かす方法。コマンド、準備のコツ、ハマりどころ、後片付けまで解説します。

1つのリポジトリで複数のコーディングエージェントを動かすなら、git worktreeは欠かせません。各エージェントがそれぞれのブランチ、それぞれのフォルダで、互いに干渉せず同時に作業できるようになります。

git worktreeとは？

通常のクローンには作業ツリーが1つしかありません。フォルダが1つ、チェックアウトされたブランチが1つです。worktreeは、同じリポジトリにひもづく追加の作業フォルダで、別のブランチをチェックアウトできます。すべてのworktreeは1つの.git履歴を共有するので、どこでコミットしてもすぐにほかのworktreeから見えますが、ファイルは別々です。

エージェントにとっては、次のような意味になります。

Claude Codeはfeat/authブランチの../atlas-authでファイルを編集できる
Codexはfeat/searchブランチの../atlas-searchでファイルを編集できる
あなたはmainブランチのメインフォルダで、レビューやアプリの実行を続けられる

誰も、ほかの誰かの変更を上書きしません。

タスクごとにworktreeを作る

メインのリポジトリフォルダで、次のように実行します。

# new branch + new folder next to the repo
git worktree add ../atlas-auth -b feat/auth
 
# another one, starting from a specific branch
git worktree add ../atlas-search -b feat/search origin/main
 
# see them all
git worktree list

あとは各フォルダでエージェントを起動します。

cd ../atlas-auth && claude
cd ../atlas-search && codex

worktreeのフォルダ名はタスクにちなんで付けましょう。1か月後、atlas-authなら意味がわかりますが、wt2ではわかりません。

Claude Codeにworktreeを作らせる

最近のClaude Codeは、worktreeを自動で作れます。

claude --worktree feature-auth   # or: claude -w feature-auth

これで.claude/worktrees/feature-auth/の下に、worktree-feature-authという新しいブランチのworktreeが作られ、その中でClaudeが起動します。別のターミナルで別の名前を付けて実行すれば、2つ目の独立したセッションになります。セッションの途中で「worktreeで作業して」とClaudeに頼むこともできます。

Claude Codeのworktreeドキュメントから、いくつか補足しておきます。

.claude/worktrees/を.gitignoreに追加しておくと、メインのチェックアウトでworktreeのファイルが未追跡として表示されません。
リポジトリには少なくとも1つのコミットが必要です。
終了時、Claudeは変更のないworktreeを削除し（名前付きのworktreeは先に確認します）、変更が残っているworktreeは残すかどうかを確認します。
.worktreeincludeファイルに、.envなどgitで無視しているファイルを書いておくと、新しいworktreeに毎回コピーされます。

タスクを担当するエージェントがClaude Codeだけならclaude --worktreeを使いましょう。フォルダ名やブランチ名を自分で決めたいとき、あるいはCodexなどほかのエージェントをworktreeで動かすときは、素のgit worktree addを使います。

エージェントを起動する前にworktreeを準備する

新しいworktreeには、gitで追跡しているファイルしか入っていません。エージェントに渡す前に、次の準備をしておきましょう。

依存関係をインストールする。 node_modules、virtualenv、ビルドフォルダは共有されません。各worktreeでnpm install（または相当するコマンド）を実行します。pnpmのように共有ストアを持つパッケージマネージャーなら速く済みます。
追跡していない設定ファイルをコピーする。 .envやローカル設定はたいていgitで無視されているので、アプリの実行に必要なものをコピーします。claude --worktreeを使う場合は、代わりに.worktreeincludeに書いておきます。
ポートを分ける。 2つの開発サーバーが両方ともポート3000で待ち受けることはできません。2つ目はPORT=3001 npm run devのように別のポートで起動します。
指示は追跡対象のファイルで共有する。 CLAUDE.mdとAGENTS.mdはgitにコミットされているので、どのworktreeにも自動で入ります。

レビュー、マージ、後片付け

エージェントの作業が終わったら、次のように進めます。

# in the worktree: check the work
git diff main...feat/auth
npm test
 
# in the main folder: merge
git merge feat/auth
 
# remove the worktree folder and its registration
git worktree remove ../atlas-auth
git branch -d feat/auth

worktreeのフォルダを手で削除してしまった場合は、git worktree pruneを実行して古いエントリを消してください。

よくあるハマりどころ

「Branch is already checked out」と出る。 1つのブランチを同時にチェックアウトできるworktreeは1つだけです。worktreeごとに新しいブランチを作りましょう。
worktreeの消し忘れ。 古いworktreeはブランチを残し続け、ディスクも消費します。ときどきgit worktree listを実行しましょう。
削除時に未コミットの変更がある。 変更が残っているworktreeでは、git worktree removeが実行を拒否します。先にコミットかstashをするか、本当に破棄したいなら--forceを使います。
エージェントがメインのフォルダを編集してしまう。 各エージェントは、リポジトリのルートではなく、そのworktreeのフォルダの中から起動してください。

Vibe Consoleでのworktree

Vibe Consoleは、エージェントが作業している間もworktreeを見える状態に保ちます。

ソース管理（⌘⇧G）のWorktreeタブに、すべてのworktreeがブランチとともに一覧表示されます。メインのworktreeと、detachedのチェックアウトには印が付きます。
worktreeをターミナルにドラッグするとパスが貼り付けられるので、そのまま**⌘K**でエージェントを起動できます。
作業が終わったらWorktree を削除で片付けられます。ローカルの変更が残っている場合は強制的に削除するか確認されます。メインのworktreeは保護されています。
グリッドには最大9つのターミナルを表示できるので、worktreeごとのエージェントにそれぞれペインを割り当てられます。エージェントを並列で動かす方法もご覧ください。

worktreeは上で紹介したgit worktree addかclaude --worktreeで作成します。どちらで作っても、すぐに一覧に表示されます。

よくある質問

worktreeはディスクを大量に使いますか？

使うのは、チェックアウトしたファイルと、そこにインストールしたものの分だけです。gitの履歴は共有されます。

worktreeと別クローン、どちらを使うべきですか？

worktreeです。履歴を共有するので、ブランチやコミットがすぐにどこからでも使え、後片付けもコマンド1つで済みます。

2つのエージェントで1つのworktreeを共有できますか？

ファイルを編集するのが多くとも1つだけなら可能です。読むだけのレビュアーエージェントなら、コードを書くエージェントとworktreeを共有できます。

14日間無料で試せます。Vibe Consoleをダウンロード。