git の worktree を使うと、Claude Code のセッションをそれぞれ独立した作業ディレクトリに閉じ込められます。片方で機能を作りながらもう片方でバグを直しても、ファイルの編集が衝突しません。この記事では、公式ドキュメントの Run parallel sessions with worktrees をもとに、起動から後片付け、サブエージェントの分離、設定の変更までを説明します。
worktree を使う理由
git の worktree は、独立した作業ディレクトリです。ファイルとブランチは自分専用ですが、リポジトリの履歴とリモートはメインのチェックアウトと共有します。
Claude Code のセッションをそれぞれ別の worktree で走らせると、一方のセッションの編集がもう一方のファイルに触れることがなくなります。片方で機能を作りながら、もう片方でバグを直す、という進め方ができます。
並列に動かす手段は worktree だけではありません。worktree が分離するのはファイルの編集で、サブエージェントやエージェントチームが調整するのは作業そのものです。役割が違うので、組み合わせて使えます。
worktree は git リポジトリを前提にします。それ以外のバージョン管理システムを使っている場合は、フックで git のロジックを差し替えます（後述）。デスクトップアプリでは、新しいセッションごとに worktree が自動で作られます。
--worktree でセッションを開始する
--worktree（短縮形 -w）に名前を渡すと、分離された worktree を作ってその中で Claude が起動します。
claude --worktree feature-auth既定では、リポジトリのルートの .claude/worktrees/<name>/ に worktree-<name> という新しいブランチで作られます。別のターミナルで違う名前を渡せば、2つ目の分離セッションが立ち上がります。名前を省略すると bright-running-fox のような名前が自動生成されます。
メインのチェックアウトで worktree の中身が未追跡ファイルとして見えないように、.gitignore に .claude/worktrees/ を足しておくとよいでしょう。
対話実行にはワークスペースの信頼が要ります。そのディレクトリで Claude を動かしたことがなければ、まず claude を一度実行して信頼のダイアログを承認してください。承認していないと --worktree はエラーで終了します。-p の非対話実行では信頼のチェックが省かれます。
worktree は新しいチェックアウトなので、開発環境の初期化は自分で行う必要があります。Claude に依存関係のインストールを頼むか、.claude/worktrees/ 配下のディレクトリでプロジェクトのセットアップを実行してください。
セッションの途中で「worktree で作業して」と頼むこともできます。このとき Claude は EnterWorktree ツールで worktree を作ります。リポジトリの .claude/worktrees/ の外に出るときは必ず承認を求められます。移動先にセッションの作業ディレクトリ・書き込み権限・CLAUDE.md などのプロジェクト設定が一緒に移るためで、この確認はパーミッションルールや「次回から聞かない」では抑制できません。
worktree の後片付け
対話セッションを終了すると、Claude は「削除すると失われる作業」が worktree に残っていないかを調べます。見るのは、変更されたファイル・未追跡ファイル・新しいコミットです。
- worktree がきれい: 名前を付けていないセッションなら、worktree とそのブランチは自動的に削除されます。名前を付けたセッションでは、後で使えるように残すかどうかを先に聞かれます。
- 作業が残っている: 残すか削除するかを聞かれます。削除を選ぶと、worktree のディレクトリとブランチが、そこにある作業ごと消えます。
-p の非対話実行には終了時のプロンプトが無いので、後片付けも行われません。git worktree remove で自分で消してください。
サブエージェントを worktree で分離する
サブエージェントをそれぞれの worktree で走らせれば、並列の編集が衝突しません。「エージェントには worktree を使って」と頼むか、カスタムサブエージェントの front-matter に isolation: worktree を書いて恒久的にします。
---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---
Apply the requested refactor across every affected file, then run the tests
and report the results.各サブエージェントには一時的な worktree が割り当てられます。変更を残さず終わった場合は自動的に削除され、変更が残っている worktree は、作業を失わずに消せるタイミングまでディスク上に残ります。
定期的な掃除は、サブエージェントとバックグラウンドセッションのために作られた worktree のうち、cleanupPeriodDays の設定より古いものを削除します。ただし変更・未追跡ファイル・未 push のコミットを抱えている worktree は飛ばされ、--worktree で自分が作った worktree は決して削除されません。
エージェントの実行中、Claude はその worktree に git worktree lock を掛けるので、並行する掃除が消してしまうことはありません。ロックはエージェントの終了時に解除されます。掃除が残した worktree を消したいときは git worktree remove を、未コミットの変更や未追跡ファイルがある場合は --force を付けて実行します。
worktree の作り方を変える
既定では、worktree は .claude/worktrees/ の下に、リポジトリの既定ブランチから分岐して作られます。この既定を変える設定が3つあります。
分岐元のブランチは worktree.baseRef で決めます。値は2つだけです。
"fresh"（既定）: リモートの既定ブランチ（多くはmain）から分岐する。リモートと同じきれいな状態から始まります。"head": ローカルの現在のHEADから分岐する。未 push のコミットや作業中のブランチの状態を持ち込みます。作業中のコードに対してサブエージェントを分離したいときはこちらです。
{
"worktree": {
"baseRef": "head"
}
}この設定にブランチ名は指定できません。特定の既存ブランチから始めたい場合は、git で直接 worktree を作ります。
プルリクエストから分岐したいときは、--worktree に # を付けたPR番号か GitHub のプルリクエストURLを渡します。origin から pull/<number>/head を取得し、.claude/worktrees/pr-<number> に作られます。シェルが # をコメントの開始と解釈しないよう、引数はクォートしてください。
claude --worktree "#1234"gitignore されたファイルの持ち込みには .worktreeinclude を使います。worktree は新しいチェックアウトなので、.env のような未追跡ファイルは存在しません。プロジェクトのルートにこのファイルを置くと、Claude が worktree を作るときに自動でコピーされます。
.env
.env.local
config/secrets.json書式は .gitignore と同じです。パターンに一致し、かつ gitignore されているファイルだけがコピーされるので、追跡済みのファイルが二重になることはありません。
git で手動管理する
特定の既存ブランチをチェックアウトしたい場合や、リポジトリの外に worktree を置きたい場合は、git で直接作ります。
# 新しいブランチで worktree を作る
git worktree add ../project-feature-a -b feature-a
# 既存のブランチから worktree を作る
git worktree add ../project-bugfix fix-issue-456
# その worktree で Claude を起動する
cd ../project-feature-a
claude
# 一覧と削除
git worktree list
git worktree remove ../project-feature-a手動で作った worktree でも、メインのチェックアウトと共有されるものは同じです。リポジトリの .git ディレクトリ（サンドボックスを有効にしていても worktree の中から git commit が通るのはこのため）、プロジェクトスコープでインストールしたプラグイン、そして Bash コマンドの「次回から聞かない」で保存したパーミッションの承認です。承認はメインのチェックアウトの .claude/settings.local.json に書かれるので、他の worktree にも効き、worktree を消しても残ります。
SVN・Perforce・Mercurial などを使っている場合は、WorktreeCreate と WorktreeRemove のフックで作成と後片付けのロジックを差し替えます。フックが既定の git の動作を置き換えるため、--worktree を使っても .worktreeinclude は処理されません。設定ファイルのコピーはフックのスクリプトの中で行ってください。