Claude Code Worktree実践ガイド — 並列セッションの隔離と落とし穴

複数のClaude Codeセッションを同時に走らせると、同じファイルを別々のセッションが書き換えて衝突します。防ぐ手立てがgit worktreeです。1つのリポジトリから物理的に別々の作業ディレクトリを生やし、セッションごとに専用のチェックアウトを与えます。Claude Codeがこの仕組みを使う経路は5つ。--worktreeフラグ、会話中の依頼、サブエージェント、バックグラウンドセッション、デスクトップアプリです。経路ごとに挙動は細かく異なります。

git worktreeの基礎 — 何が共有され何がされないか

git worktreeはGit本体の標準機能です。1つの.gitディレクトリを複数の作業ディレクトリで共有します。メインの作業コピーを~/repoとすると、~/repo/.claude/worktrees/feature-xのような別ディレクトリを追加し、そこに別のブランチをチェックアウトできます。複製cloneより軽量です。.git実体を持たないぶん、1回のfetchが全worktreeに反映されます。

共有される範囲とされない範囲は明確です。

extensions.worktreeConfigを有効にするとcore.worktreeやcore.sparseCheckoutのようにworktreeごとに独立させたい設定だけを分離できます。Git公式の見解は明確です。複数チェックアウトについて「サブモジュールのサポートは不完全で、スーパープロジェクトの複数チェックアウトは推奨しない」と明記しています。サブモジュールを使うリポジトリなら、本格運用の前に確認しておく価値があります。

Claude Codeがworktreeを作る5つの起点

Claude Codeがworktreeを作る経路は5つです。どれも最終的には同じgit worktreeの仕組みに乗りますが、保存先やクリーンアップの主導権が違います。

--worktreeフラグでセッションを隔離する

-wまたは--worktreeに名前を渡すと、隔離されたworktreeを作ってその中でClaude Codeを起動します。保存先は既定で.claude/worktrees/<name>/です。ブランチ名はworktree-<name>になります。

claude --worktree feature-auth

別のターミナルで別名を指定して同じコマンドを実行すれば、2つ目の隔離セッションが立ち上がります。名前の省略も可能です。その場合はbright-running-foxのような名前が自動生成されます。

対話実行にはワークスペース信頼が必要です。そのディレクトリでClaude Codeを一度も実行したことがなければ、先にclaudeを1回実行して信頼ダイアログを通すか、--worktreeがエラーで促してきます。-pを使う非対話実行はこの信頼チェックをスキップするため、claude -p --worktreeはそのまま進みます。

worktreeは新規チェックアウトなので、依存関係のインストールなど環境構築が必要です。.claude/worktrees/は自分のリポジトリの.gitignoreに加えておくと、メインの作業コピーに未追跡ファイルとして出てこなくなります。

会話の途中でworktreeへ移る — EnterWorktreeツール

セッションの途中で「worktreeで作業して」と頼むと、Claude CodeはEnterWorktreeツールでworktreeを作って移動します。すでにworktree内にいる場合は、EnterWorktreeに移動先パスを渡すことで別のworktreeへ切り替えられ、直前のworktreeはディスク上にそのまま残ります。

.claude/worktrees/の外側にあるパスへ入ろうとするときは、必ず承認を求められます。移動によってセッションの作業ディレクトリ・書き込み権限・CLAUDE.mdや設定などのプロジェクト構成がそのパスに切り替わるためです。この確認はEnterWorktreeの権限ルールや「今後確認しない」を選んでも省略されず、bypassPermissionsモードのときだけスキップされます。v2.1.206より前は、既存のworktreeパスへは確認なしで入れていました。

worktreeの後片付けとセッション再開

対話セッションのworktreeを終了するとき、Claude Codeは削除によって失われる作業(変更・未追跡ファイル・新規コミット)がないか確認します。

• worktreeがきれいな場合: 名前を指定しなかったセッションはworktreeとそのブランチを自動で削除します。名前付きセッションは先に確認を挟み、あとで再利用できるよう残す選択もできます
• worktreeに作業が残っている場合: 保持するか削除するかを確認されます。保持すればディレクトリとブランチはそのまま、削除すれば中身ごと消えます

-pを使う非対話実行には終了時の確認プロンプトがないため、worktreeは自動で片付きません。git worktree removeで手動削除します。Windowsでは、worktreeの削除がworktree外のファイルまで削除することはありません。ただしworktree内のフォルダがNTFSジャンクションやディレクトリシンボリックリンクの場合、削除されるのはリンクだけで、リンク先の実体は残ります(v2.1.205より前は、サブディレクトリにネストしたリンクの削除でリンク先の実体まで消えるケースがありました)。

セッションを再開すると、そのセッションが使っていたworktreeに戻ります。この挙動は対話再開だけでなく、非対話モードの--continue・--resume、Agent SDKでも同じです。worktree内からExitWorktreeで抜けることもできます。--fork-sessionで分岐した再開は起動時のディレクトリで始まり、元のセッションのworktreeには影響しません。worktreeディレクトリがすでに存在しない場合も、起動時のディレクトリで再開します。v2.1.198以降、worktreeへの出入りは/cdと同じ扱いでトランスクリプトの記録先も追従します(/desktopや--resumeもその移動先で見つけられます)。

サブエージェントをworktreeで隔離する

サブエージェントは既定でメインセッションと同じ作業ディレクトリで動きます。並列で走る複数のサブエージェントに同じファイルを触らせたくないときは、.claude/agents/のfrontmatterに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で実行され、変更を残さず終了すると自動で削除されます。変更が残っている場合はディスク上に残り、設定cleanupPeriodDays(既定30日)の期限を過ぎたタイミングで定期スイープが安全に削除します。サブエージェントのworktreeは--worktreeと同じ基点(次節のworktree.baseRef)を使うため、設定を"head"にしない限りリポジトリの既定ブランチから分岐します。

エージェントが実行中の間、Claude Codeはそのworktreeにgit worktree lockをかけて並行するクリーンアップから守ります。ロックはエージェント終了時に解放され、v2.1.210以降はプロセスが強制終了したバックグラウンドセッションのロックも自動解放されます(それより前はgit worktree unlockが必要でした)。

安全機構はここで終わりません。v2.1.203以降、isolation: worktreeのサブエージェントがBash/PowerShellコマンドを実行する作業ディレクトリがメインの作業コピーに解決されると、エラーで失敗します(それ以前はメインの作業コピーで実行できてしまいました)。v2.1.210以降はこのチェックがリポジトリ全体に拡張され、セッション自身がworktree内にいる場合は連携元のメインチェックアウトも対象になります。v2.1.216以降はBashコマンドの中身も検査し、git -C・--git-dir・GIT_DIR/GIT_WORK_TREE環境変数・cdでのメインチェックアウトへの迂回といった手口でgitをメイン側へ向けるコマンドもエラーで止めます。複雑すぎて解析できないコマンドも、単純なコマンドに分けるよう促すエラーで弾かれます。この検査はBashのみが対象で、PowerShellは作業ディレクトリのチェックだけが働きます。

サブエージェント自体の設計・並列パターンはサブエージェント完全活用とSub-agents完全ガイドにまとめています。

バックグラウンドセッションとデスクトップアプリの自動隔離

claude agentsで開くagent view、/bg、claude --bgで起動したバックグラウンドセッションは、ファイル編集の直前に自動で.claude/worktrees/配下のworktreeへ移動します。すでにリンク済みのworktree内にいる場合、作業ディレクトリがgitリポジトリでなくWorktreeCreateフックも未設定な場合、書き込み先が作業ディレクトリの外側の場合は、この移動をスキップします。

隔離が不要なリポジトリでは、設定でこの自動移動そのものを無効化できます。

{
  "worktree": {
    "bgIsolation": "none"
  }
}

既定値は"worktree"で、EnterWorktreeが呼ばれるまでメインの作業コピーへのEdit/Writeをブロックします。"none"にするとバックグラウンドジョブが作業コピーを直接編集するようになります(v2.1.143以降)。worktree内でコード変更を隔離したバックグラウンドセッションは、止まって確認することなく自分のブランチへコミット・pushしてドラフトPRを開きます。mainやmasterへの直接pushやマージはしません。

削除方法にも違いがあります。agent viewでCtrl+Xを2回押すと、未コミットの変更ごとworktreeが削除されます。残したい変更は先にコミットしておく必要があります。シェルからclaude rmで削除する場合、未コミットの変更が残るworktreeはそのセッション行ごと保持されます。どちらの操作も、どこにもpushされていないコミットが残るworktreeは削除しません。

デスクトップアプリでは、新規セッションを作るたびにGitリポジトリなら自動でworktreeが割り当てられ、1つのセッションで加えた変更はコミットするまで他のセッションに影響しません。保存先は既定で<project-root>/.claude/worktrees/ですが、設定の「Worktree location」でカスタムディレクトリに変更でき、worktreeのブランチ名に付くプレフィックスも設定できます。セッションをアーカイブすると対応するworktreeも削除され、PRのマージやクローズをきっかけに自動アーカイブする設定も用意されています。

エージェントの状態を1画面で束ねる運用はagent view: 複数セッションを束ねる常駐プロセス設計で扱っています。

worktree・サブエージェント・agent view・agent teamsの使い分け

Claude Codeで作業を並列化する手段は複数あり、それぞれ「誰が調整するか」「作業者同士が話すか」「同じファイルを触るか」で選び分けます。

worktreeはこの4つとは層が違います。ファイル編集を隔離するための道具で、単独の並列化スタイルではありません。自分で走らせるセッションにはworktreeを使い、agent viewが起動するセッションは自動的に専用worktreeへ移り、スポーンしたサブエージェントもそれぞれworktreeを持てます。一方でagent teamsはチームメイトをworktreeで隔離しないため、担当ファイルを分けて競合を避ける設計が必要です。大きな一括変更を5〜30個のworktree隔離サブエージェントに分けてそれぞれPRを開かせる/batchスキルも、この仕組みの上に成り立つ既製パターンです。

作業を指揮役と実行役に分けてサブエージェントへ振る設計はオーケストレーター設計、台本駆動で大量のサブエージェントを回す仕組みはダイナミックワークフローとはで詳しく扱っています。

baseRefでworktreeの起点を選ぶ

新規worktreeは既定でリポジトリの既定ブランチから分岐します。現在の作業の続きとしてworktreeを切りたいときは、設定のworktree.baseRefを変更します。この設定は--worktreeだけでなく、会話中のEnterWorktreeツールやサブエージェント隔離にも同じく適用されます。

{
  "worktree": {
    "baseRef": "head"
  }
}

選べる値は2つです。

• "fresh"(既定): リモートのorigin/<default-branch>(通常はmain)から分岐し、常にリモートと一致したきれいな状態で始まります
• "head": ローカルの現在のHEADから分岐し、未pushのコミットや作業中のブランチの状態を引き継ぎます。進行中の作業に対してサブエージェントを隔離したいときに向きます。リンク済みworktreeの内側では、"head"はそのworktree自身のHEADを指し、メインの作業コピーのものではありません

worktree.baseRefに特定のブランチ名を直接指定することはできません。既存の特定ブランチから始めたいときは、後述するgit worktree addで手動作成します。

"fresh"を使う場合、Claude Codeはorigin/HEADを裏で最新に保ちます。直近24時間以内にfetchしていなければ既定ブランチをfetchし(最大5秒でタイムアウト)、fetchに失敗すればローカルにキャッシュされた参照を使います。リモートが設定されていない場合やorigin/HEADがキャッシュされておらずfetchもできない場合は、ローカルの現在のHEADにフォールバックします(v2.1.208より前は、ローカルにキャッシュされていたorigin/HEADをそのまま使っていました)。

特定のPull Requestから分岐したいときは、--worktreeにPR番号を#付きで渡すか、GitHubのPR URLをそのまま渡します。シェルが#をコメントの開始と解釈しないよう、引用符で囲みます。

claude --worktree "#1234"

このコマンドはoriginからpull/<number>/headをfetchし、.claude/worktrees/pr-<number>にworktreeを作ります。

すでに存在する名前を--worktreeに渡すと、新規作成ではなく既存のworktreeを開きます。既定の"fresh"基点では、次の条件をすべて満たすときだけリポジトリの既定ブランチにリセットされます。未コミットの変更や未追跡ファイルがないこと、Claude Codeが作ったブランチのままであること、独自コミットがないか、あってもPull Requestがマージ済みでリモートブランチが削除されていること。それ以外は古い状態のまま再オープンされます(v2.1.208より前は、名前の再利用は常に古い状態のまま再オープンでした)。

node_modulesなど大きい依存の扱い方

worktreeは新規チェックアウトなので、node_modulesのような依存ディレクトリは最初から存在しません。素朴に毎回インストールし直すと、ディスク消費とインストール時間の両方が膨らみます。Claude Codeにはこれに対応する設定が3つ用意されています。

worktree.symlinkDirectoriesは、指定したディレクトリをメインリポジトリから各worktreeへシンボリックリンクし、ディスク上での重複を避けます。既定では何もリンクされません。

{
  "worktree": {
    "symlinkDirectories": ["node_modules", ".cache"]
  }
}

大規模なモノレポでは、worktree.sparsePathsでgitのsparse-checkoutを使い、指定したディレクトリとルート直下のファイルだけをworktreeに書き出す設定もあります。ディスクへの書き込み量そのものを減らせるため、リポジトリ全体が巨大なケースに向きます。

{
  "worktree": {
    "sparsePaths": ["packages/my-app", "shared/utils"]
  }
}

.envのようなgitignore対象の設定ファイルは、シンボリックリンクではなく.worktreeincludeファイルで個別にコピーします。プロジェクトルートに置き、書式は.gitignoreと同じです。gitignoreされていてかつパターンに一致するファイルだけがコピーされるため、追跡対象のファイルが誤って重複することはありません。

.env
.env.local
config/secrets.json

この.worktreeincludeは、--worktreeで作るworktree・サブエージェントのworktree・デスクトップアプリの並列セッションのすべてに適用されます。WorktreeCreateフックで独自の作成ロジックに置き換えている場合はこのファイルが処理されないため、コピー処理はフックのスクリプト内に自分で書きます。

worktree間で共有されるもの・されないもの

worktreeは専用のファイルとブランチを持ちますが、メインの作業コピーと共有しているものが3つあります。作成経路が--worktreeでもgit worktree addでもデスクトップアプリでも、この3つはどれも同じように働きます。

• .gitディレクトリ: worktree内のgitコマンドはメインリポジトリの共有.gitディレクトリに書き込みます。sandboxing(ファイルシステムへの書き込みを制限する隔離機能)はこの書き込みを許可するため、sandbox有効時でもworktree内からgit commitが問題なく動きます
• プラグイン(v2.1.200以降): メインの作業コピーでプロジェクトスコープにインストールしたプラグインは、同じリポジトリのworktreeでもそのまま読み込まれ、worktreeごとの再インストールは不要です
• 権限承認(v2.1.211以降): worktreeセッションでBashコマンドを「今後確認しない」で承認すると、その規則はメインの作業コピーの.claude/settings.local.jsonに保存され、メインの作業コピーでも他の全worktreeでも適用され、worktreeを削除しても残ります。v2.1.211より前は承認内容がそのworktree内に保存されるだけで、他の場所には適用されず、worktreeを削除すると失われていました

設定ファイルの解決先は、ファイルによって分かれます。権限承認が書き込まれる.claude/settings.local.jsonは、上記のとおりv2.1.211以降はサブディレクトリやworktreeから起動してもリポジトリルート(メインの作業コピー)のものが読み込まれます。一方.claude/settings.jsonとClaude Code側のフック定義は起動ディレクトリの.claude/だけを見ており、親ディレクトリへのフォールバックはありません。

設定項目そのものの全体像はsettings.json完全ガイドにまとめています。

pushする前に確認しておきたいこと

worktreeそのものに固有の危険ではありませんが、複数のworktreeを行き来していると見落としやすい落とし穴があります。Gitのpushは引数を省略するとpush.defaultの設定に従って挙動が決まり、既定値はGit 2.0以降"simple"(現在のブランチと同名のリモートブランチへpush)です。ここを"upstream"に変更していると、git pushは現在のブランチの@{upstream}、つまりそのブランチが追跡しているリモートブランチへ直接pushします。

手動でgit worktree addする際に、ブランチを作らず既存のリモート追跡ブランチ(たとえばorigin/main)を直接チェックアウトすると、そのローカルブランチの上流がmainになっている場合があります。この状態でpush.defaultが"upstream"だと、意図せずmainへ直接pushしてしまう構図が成立します。worktreeで作業する前に、現在のブランチの上流を確認しておくと安全です。

git rev-parse --abbrev-ref --symbolic-full-name @{push}

手動でのworktree管理とGit以外のVCS対応

git worktreeコマンドを直接使うのは、特定の既存ブランチをチェックアウトしたいときや、worktreeをリポジトリの外側に置きたいときです。

git worktree add ../project-feature-a -b feature-a
cd ../project-feature-a
claude

一覧・削除・ロックなど、サブコマンドは用途ごとに揃っています。

PRレビューでこの手動管理を使う場面もあります。レビュー対象のブランチを別worktreeでチェックアウトすれば、進行中の自分の作業を止めずに動作確認できます。Claude Codeでgh pr createを使ってPRを作ると、セッションはそのPRに自動でリンクされ、あとからclaude --from-pr <番号>でそのPRに紐づくセッションを絞り込んで再開できます。

Gitではないバージョン管理(SVN・Perforce・Mercurial等)を使うリポジトリでは、WorktreeCreateとWorktreeRemoveのフックで作成・削除のロジックそのものを置き換えられます。WorktreeCreateフックは標準出力にworktreeのパスを返す必要があり、ゼロ以外の終了コードを返すとworktree作成自体が中止されます。WorktreeRemove側は通知イベントで、ここで何を返してもworktreeの削除は止められません。この場合、.worktreeincludeはGitのロジックを前提にしているため処理されず、gitignore対象ファイルのコピーはフックのスクリプト内に自分で書きます。

フックの入力スキーマ・実行タイプ・設定ファイルの書き方はHooks完全ガイド、ユースケース別のレシピはHooks実例カタログにまとめています。

つまずきやすい落とし穴

削除忘れ: git worktree removeを忘れると、そのブランチをgit branch -dしようとしたときに「worktreeでチェックアウト中」と拒否されます。git worktree listで定期的に棚卸しする習慣が実質的な対策です。

シンボリックリンク化されたパスでの作成拒否: .claude・.claude/worktrees・worktreeディレクトリ自体がシンボリックリンクの場合、Claude Codeはworktreeの作成そのものを拒否し、そのパスをエラーで示します。v2.1.212より前は、リポジトリにコミット済みのシンボリックリンクがこれらのパスにあると素通りしてしまい、リポジトリの外側にファイルを作成してしまうことがありました。

起動時のworktree進入失敗: WorktreeCreateフックが作成したディレクトリ以外の文字列を出力した場合や、セットアップ後にディレクトリが削除された場合、Claude Codeはパス名を含むエラーを出して終了コード1で終わります。v2.1.205より前はセッションごとクラッシュし、-p使用時は終了コード0になるまで約30秒スタックしていました。

大きいリポジトリでのディスク消費: .gitは共有されますが、チェックアウトしたファイル群はworktreeごとに実体として存在します。10GBのリポジトリを5つworktreeで切れば単純計算で50GB近くになるため、symlinkDirectoriesやsparsePathsを検討する価値があります。ただしsparsePathsはsparse worktreeが存在する間、共有.git/configのextensions.worktreeConfigを有効化する副作用を伴います。go-git系のサードパーティ製gitツールを併用している場合は、この設定変更が影響しないか確認しておくと安全です。

大きい失敗の再現・回避策はClaude Codeが期待通りに動かない10シナリオ、開発環境をコンテナ単位で隔離する別のアプローチはDevContainerで安全に動かす完全実装で扱っています。worktreeはディレクトリ単位の隔離、DevContainer sandboxはプロセス・認証情報単位の隔離で、目的が異なるぶん組み合わせて使えます。

よくある質問

worktreeとサブエージェントの隔離は何が違いますか

worktreeはファイルを物理的に別ディレクトリへ分ける仕組みで、サブエージェントは1つの会話の中でタスクを委譲してコンテキストを分ける仕組みです。両者は独立した軸で、isolation: worktreeを指定すればサブエージェントにworktreeも与えられます。

.claude/worktrees/はコミットする必要がありますか

不要です。.gitignoreに加えておくと、worktreeの中身がメインの作業コピーで未追跡ファイルとして表示されなくなります。

worktreeを作るたびにnpm installが必要ですか

worktreeは新規チェックアウトなので、既定では必要です。worktree.symlinkDirectoriesでnode_modulesをシンボリックリンクするか、大規模モノレポならworktree.sparsePathsで必要な範囲だけをチェックアウトすることで、この手間を減らせます。

worktreeを削除するとブランチも消えますか

Claude Codeが自動でクリーンな未使用worktreeを削除する場合は、ブランチごと削除されます。git worktree removeで手動削除した場合はディレクトリだけが消え、ブランチは残るため、不要ならgit branch -dが別途必要です。

baseRefを"head"にするとどう変わりますか

既定の"fresh"はリモートの既定ブランチから常にきれいな状態で分岐しますが、"head"はローカルの現在のHEADから分岐し、未pushのコミットや作業中の状態を引き継ぎます。進行中の作業を土台にサブエージェントを走らせたいときに向きます。

worktree内でgit commitは正しく動きますか

動きます。worktreeはメインリポジトリの.gitディレクトリを共有しており、sandboxが有効な環境でもこの共有.gitへの書き込みは許可されています。

Windowsでworktreeを使うときの注意点はありますか

worktreeの削除はworktree外のファイルには影響しません。ただしworktree内のフォルダがNTFSジャンクションやディレクトリシンボリックリンクの場合、削除されるのはリンクだけでリンク先の実体は残ります。Codeタブの利用にはGit for Windowsのインストールが必要です。

まとめ

Claude Codeにおけるworktreeは、--worktreeフラグ・会話中のEnterWorktree・サブエージェントのisolation: worktree・agent viewなどのバックグラウンドセッション・デスクトップアプリの自動隔離という5つの起点を持ち、どれも同じgit worktreeの上に成り立っています。baseRefの"fresh"/"head"、symlinkDirectoriesやsparsePathsによる依存関係の軽量化、権限承認やプラグインがメインの作業コピー側に共有される仕組みまで押さえておくと、複数セッションを並走させたときの「なぜこうなるか」を都度調べずに済みます。ファイル単位の隔離はworktree、タスクの委譲はサブエージェントやagent teams、と役割を分けて考えると、並列化の設計で迷いにくくなります。