worktree で並行作業

git の worktree は、同じリポジトリの履歴とリモートを共有しながら、独自のファイルとブランチを持つ別の作業ディレクトリです。セッションごとに worktree を分ければ、1つのセッションの編集がほかのセッションのファイルに及びません。機能の実装と別のバグ修正を同時に進められます。

• claude --worktree <名前>（-w）で、隔離された worktree を作ってその中で始める
• 終了時に、未コミットの作業があるかを調べて、残すか消すかを聞いてくれる
• サブエージェントも、isolation: worktree で自分専用の worktree で動かせる
• 作成時の基点ブランチ・gitignore されたファイルのコピー・作成そのものの置き換え（フック）を設定できる
• git 以外のバージョン管理でも、フックで同じ隔離ができる

worktree はファイル編集の隔離を担います。ほかの並列の方法との比べ方は並列作業の選び方、1つのセッション内の分担はサブエージェント、worktree 間で調査結果を渡すにはセッション間のメッセージ、バックグラウンドのエージェントビューから投入したセッションは自動で自分の worktree に入ります。

worktree で Claude を始める#

--worktree（または -w）に名前を渡すと、隔離された worktree を作ってその中で Claude を始めます。既定では、リポジトリのルートの .claude/worktrees/<名前>/ に、worktree-<名前> という新しいブランチで作られます。

claude --worktree feature-auth

別の端末で別の名前を付けて実行すれば、2つ目の隔離セッションになります。名前を省くと、bright-running-fox のような名前が自動でつきます。

対話的な実行はワークスペースの信頼が必要です。そのディレクトリで初めて Claude を使うなら、先に claude を一度実行して信頼ダイアログを承認してください。承認がないと --worktree はエラーで終了します。-p での非対話の実行は信頼の確認を飛ばすので、claude -p --worktree はそのまま進みます。

開発環境を整える#

worktree は新しいチェックアウトなので、開発環境をそこで初期化します（Claude に依存関係のインストールを頼むか、.claude/worktrees/ の下で自分でセットアップを実行する）。.env のような gitignore されたファイルを新しい worktree に自動で持ち込むには、.worktreeinclude ファイルを使います（下の「gitignore されたファイルをコピーする」）。

Claude に worktree を作らせる#

会話の中で「worktree で作業して」と頼むと、EnterWorktree ツールで作られます。worktree の中にいる Claude は、.claude/worktrees/ の下の別の worktree へ、EnterWorktree にパスを渡して直接移れます（前の worktree はそのまま残る）。

リポジトリの .claude/worktrees/ の外のパスへ入ろうとすると、Claude Code が先に承認を求めます。移動で、セッションの作業ディレクトリ・書き込み権限・CLAUDE.md や設定などのプロジェクト構成がその場所に移るためです。EnterWorktree の権限ルールや「don't ask again」ではこのプロンプトは消えず、bypassPermissions モードだけが飛ばします。v2.1.206 より前は、既存の worktree のパスなら確認なしで入れました。

worktree を後片付けする#

対話的な worktree セッションを終えるとき、Claude は、worktree を消すと失われる作業（変更・未追跡のファイル、チェックアウト済みのサブモジュール内の未コミットの作業、新しいコミット）がないかを調べます。これは Claude が git で作った worktree の規則です。WorktreeCreate フックで作った worktree は、WorktreeRemove の側で扱います。

• worktree がきれい：名前なしのセッションなら、Claude が worktree とブランチを自動で消す。名前をつけたセッションなら、あとで使えるよう先に確認される
• 作業が入っている：残すか消すかを聞かれる。残せばディレクトリとブランチが保たれ、終了時に出る claude --worktree <name> --resume で戻れる。消すと、worktree のディレクトリとブランチが、中の作業ごと消える
• 状態を確かめられない：変更を数えられない、サブモジュールのチェックアウトを調べられないときは、自動で消さずに確認される。何を確かめられなかったかが示される

-p の非対話の実行には終了時のプロンプトがなく、Claude は worktree を片づけません。作成時にかけたロックは、あとのセッションの古いロックの掃除が外すまで残ります。消すには git worktree remove を実行します。ロックのために git が拒否したら、先に git worktree unlock を実行します。

Windows で worktree を消しても、その外のファイルは消えません。worktree の中のフォルダが別の場所へのリンク（NTFS ジャンクションやディレクトリのシンボリックリンク）なら、リンクだけを消し、指す先のフォルダは残します。v2.1.205 より前は、サブディレクトリにリンクがあると、その指す先が消えることがありました。

worktree のセッションを再開する#

上の後片付けの手順（終了）を踏まずに worktree の中で終わったセッションを再開すると、Claude Code はセッションをその worktree へ戻します。対話の再開、-p の非対話モードでの --continue と --resume、Agent SDK でも同じです。--continue は、起動したディレクトリで記録された最新のセッションを選びます。戻ったあとも、Claude は ExitWorktree ツールで抜けられます。

戻す前に、その worktree がメインとは別のチェックアウトであることを確かめ、確認に通らないものには入り直しません。git の worktree は git のメタデータを読んで確認します。WorktreeCreate フックで作ったような git のメタデータのない worktree は通ることがあります。

起動の場所と再開の仕方で、Claude Code が入り直す先が変わります。

• 起動ディレクトリ：メインのチェックアウトか、リポジトリの別のディレクトリから --resume する。Claude Code が .claude/worktrees/ の下に git で作った worktree には、その中から起動しても入り直す。それ以外の worktree の中から起動したときは、そこから保証できる場合だけ入り直す（それ自体がリポジトリのもの、git のメタデータがないもの、git worktree add で作った worktree のサブディレクトリからの起動は断られるので、メインのチェックアウトから起動する）
• --fork-session：フォークしたセッションは起動したディレクトリで始まり、元のセッションの worktree には触れない
• 消えた worktree：ディレクトリがもうなければ、起動したディレクトリで再開し、worktree が消えたことを伝えて、セッションの worktree との結びつきを解く

Claude が git で作った worktree に入る・出るとき、トランスクリプトもついていきます。/cd と同じように、セッションの新しい作業ディレクトリのもとに記録され、/desktop や --resume がそこで見つけられます。出るときも同様に戻ります。WorktreeCreate フックで作った worktree のトランスクリプトは、起動ディレクトリに置かれたままです（v2.1.198 以降）。

隔離を強制するしくみ#

セッションが worktree に隔離されている間、Claude Code は次の4つの確認が定めるツール呼び出しをブロックします。--worktree で始めた場合も、EnterWorktree で入った場合も、worktree のセッションを再開した場合も、同じ規則です。対話でもバックグラウンドでも、隔離されたセッションから起こしたすべてのサブエージェントにも同じ強制が及びます。

確認は、Claude Code を起動したリポジトリに適用され、リンクされた worktree の元のメインのチェックアウトにも及びます。PowerShell のコマンドには、作業ディレクトリの確認だけが適用されます。拒否は、worktree の名前と進め方を示すツールエラーとして Claude に返ります。

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

サブエージェントを自分専用の worktree で動かせば、並列の編集がぶつかりません。Claude に「エージェントには worktree を使って」と頼むか、カスタムサブエージェントの frontmatter に isolation: worktree を足して恒久にします。.claude/agents/ に置く次のサブエージェントは、常に自分の 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 が与えられ、変更なしで終われば Claude Code が自動で消します。変更のある worktree は、下の定期的な掃除が作業を失わずに消せるようになるまで、ディスクに残ります。サブエージェントの worktree は --worktree と同じ基点ブランチを使うので、worktree.baseRef が "head" でなければ、リポジトリの既定ブランチから分かれます。

worktree の中で動くサブエージェントが起動時に読む指示ファイルは、その worktree ではなく、メインの会話のものです。worktree が既定の場所（.claude/worktrees/）にあるときは、サブエージェントがそこでファイルを読んでも、worktree の直下の CLAUDE.md と .claude/rules/ は読み込みません。worktree のブランチで内容が違っていても同じです。

サブエージェントとバックグラウンドセッションの worktree の掃除#

Claude Code は、サブエージェントとバックグラウンドセッションのために作った worktree を、cleanupPeriodDays より古くなったものから定期的な掃除で消します。--worktree のセッションをバックグラウンドへ移すと、その worktree はバックグラウンドセッションの worktree として掃除の対象になります。掃除は、次の場合は worktree を残します。

• worktree に作業が残っている（変更・未追跡のファイル・未 push のコミット）
• チェックアウト済みのサブモジュールに変更・未追跡のファイルがある、または worktree のサブモジュールを調べられない（v2.1.274 以降）
• 作成をブロックする4つのケース（下のトラブルシューティングの Git LFS の節）のどれかに当たる
• バックグラウンドへ移していない --worktree のセッションの worktree（古さにかかわらず）
• 自分で git worktree add で作った worktree（その中で --worktree <name> のセッションを動かしてバックグラウンドへ移した場合でも）

Claude Code は git で作ったすべての worktree の git メタデータに目印を書き、目印のない worktree（WorktreeCreate フックで作ったものを含む）は、掃除が残します。エージェントが動いている間、Claude Code はその worktree に git worktree lock をかけて、同時の掃除に消されないようにし、エージェントが終わると外します。バックグラウンドセッションのために作った worktree にも、セッションが動いている間は同じロックをかけるので、掃除は残し、git worktree remove も拒否します。

掃除は、プロセスが終了したセッションのために Claude Code がかけたロックも外すので、強制終了されたバックグラウンドセッションが worktree をロックしたままにしません。自分で git worktree lock をかけたロックは外しません（v2.1.210 より前は、強制終了されたセッションが残したロックを git worktree unlock で自分で外すまで残りました）。掃除が残した worktree を片づけるには git worktree remove を実行します。変更や未追跡のファイルがあれば --force を足し、ロックで拒否されたら先に git worktree unlock します。

worktree の作り方を変える#

既定では、.claude/worktrees/ の下に作られ、リポジトリの既定ブランチから分かれ、追跡されているファイルだけがチェックアウトされます。このセクションの設定で変えられます。

基点ブランチを選ぶ#

新しい worktree は、リポジトリの既定ブランチから分かれます。いまの作業から分かれたいときは、設定の worktree.baseRef を使います。

worktree.baseRef にブランチ名は指定できません。特定の既存のブランチから始めるには、git で直接作ります（下の「手動で管理する」）。"fresh" では、Claude Code は origin/HEAD を新しく保ちます。最後の取得から24時間以上経っていれば、既定ブランチを最大5秒で取得し、取得に失敗したらローカルにキャッシュされた参照を使います。この取得はターミナルでの入力を待たないので、git や ssh がパスワード・鍵のパスフレーズ・新しい SSH ホストの確認を求める場合も、失敗として扱われます。リモートが未設定、または origin/HEAD がローカルになく取得もできないときは、ローカルの現在の HEAD から作ります（v2.1.208 より前は、ローカルにキャッシュされていた origin/HEAD をそのまま使いました）。

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

プルリクエストから分かれる#

特定のプルリクエスト（マージリクエスト）から分かれるには、--worktree に # 付きの番号、GitHub の PR の URL、または https://gitlab.com/group/repo/-/merge_requests/123 のような GitLab のマージリクエストの URL を渡します。その変更の head のコミットを origin から取得し、.claude/worktrees/pr-<番号> に worktree を作ります。シェルが # をコメントの始まりと取らないよう、引数は引用符で囲みます。

claude --worktree "#1234"

URL からは番号だけを読み、常に origin から取得します。取得の経路は origin のホストで決まります。

v2.1.233 より前は、#<番号> と GitHub 形式の PR の URL だけを受け付け、常に pull/<number>/head を取得しました。

この取得も、ターミナルでの入力を待ちません。git や ssh がパスワード・鍵のパスフレーズ・新しい SSH ホストの確認を求めると、取得は失敗し、Claude Code は Error creating worktree: Failed to fetch PR/MR #<number> のメッセージで終了します。ssh-agent が持つ鍵は使えるので、始める前に鍵をそこへ読み込み、新しいホストは git fetch を一度手で実行して記録しておきます。

gitignore されたファイルをコピーする#

worktree は新しいチェックアウトなので、メインのリポジトリの .env や .env.local のような未追跡のファイルはありません。Claude が worktree を作るときに自動でコピーするには、プロジェクトのルートに .worktreeinclude ファイルを置きます。書式は .gitignore と同じで、パターンに合い、かつ gitignore されているファイルだけがコピーされます（追跡されているファイルは重複しません）。

.env
.env.local
config/secrets.json

**/ で始まるパターンで、欲しいファイルがディレクトリごと gitignore されている場合、そのディレクトリ自体がパターンに合うか、**/ の次の最初の名前がそのディレクトリのパスにある名前のどれかであるときにだけコピーされます。たとえば **/.claude/skills/*.md なら、最初の名前が .claude なので、無視された .claude/ からコピーされます。**/ のパターンが届かない無視されたディレクトリから取るには、パターンでディレクトリを名指しします（vendor/**/config.json のように）。

これは、git で作るすべての worktree（--worktree・サブエージェントの worktree・デスクトップアプリの並列セッション）に効きます。WorktreeCreate フックを使うときは、フックのスクリプトの中でコピーします。

worktree の名前を再利用する#

すでにディレクトリがある名前を --worktree に渡すと、新しく作らず、その既存の worktree が開きます。基点が既定の "fresh" のとき、開き直した worktree は、次のすべてが当てはまれば、古い先端で続けず、リポジトリの既定ブランチへリセットされます。

• 未コミットの変更も未追跡のファイルもない
• Claude Code が作ったブランチにまだいる
• 自分のコミットがない、またはそのプルリクエストがマージされ、リモートのブランチが削除されている

マージ済みの検出は git の状態だけで行います（worktree が push したリモートのブランチがもうなく、worktree のコミットがすべて既定ブランチにある）。それ以外では、古い先端のまま開き直します（条件のどれかに外れる・状態を確かめられない・worktree.baseRef が "head"・名前が PR やマージリクエストの参照）。v2.1.208 より前は、名前を再利用すると、常に古い先端で開き直しました。

フックで作成を置き換える#

WorktreeCreate フックで、既定の git worktree の処理をそっくり置き換えられます。worktree を .claude/worktrees/ 以外へ置くこともできます。完全な例は次の節です。

メインのチェックアウトと共有するもの#

worktree は自分のファイルとブランチを持ちますが、次のものはメインのチェックアウトと共有します。--worktree でも git worktree add でもデスクトップアプリ経由でも同じです。

• リポジトリの .git ディレクトリ：worktree の中の git コマンドは、メインのリポジトリの共有の .git に書く。サンドボックスもその書き込みを許すので、サンドボックスが有効でも worktree の中で git commit が使える
• プラグイン：メインのチェックアウトからプロジェクトスコープで入れたプラグインは、同じリポジトリの worktree でも読み込まれ、worktree ごとに入れ直す必要がない（v2.1.200 以降）
• 権限の承認：worktree のセッションで Bash コマンドに「Yes, and don't ask again」を選ぶと、ルールはメインのチェックアウトの .claude/settings.local.json に保存され、メインと同じリポジトリのほかのすべての worktree に効き、worktree の削除後も残る。Windows など Claude Code がリポジトリのルートを使わない場合は、ルールはその worktree に残る。v2.1.211 より前は、worktree での承認はその worktree の中に保存され、ほかに効かず、worktree を消すと失われた
• 未追跡のスキル・エージェント・コマンド：worktree のチェックアウトのルートに .claude/skills がない（たとえば .claude/skills が gitignore されている）ときは、Claude Code は worktree のセッションで、メインのチェックアウトのプロジェクトのスキルを読む。worktree に自分の .claude/skills があれば、そのコピーだけが読まれる。.claude/agents と .claude/commands にも同じ読み通しがある。スキルの読み通しには v2.1.277 以降が要る

手動で管理する#

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

# 新しいブランチで worktree を作る
git worktree add ../project-feature-a -b feature-a

# 既存のブランチ（fix-issue-456 は実在するブランチに置き換える）から作る
git worktree add ../project-bugfix fix-issue-456

# worktree で Claude を始める
cd ../project-feature-a
claude

# worktree を一覧する
git worktree list

# 使い終わったら消す
git worktree remove ../project-feature-a

git 以外のバージョン管理#

worktree の隔離は、既定では git を使います。SVN・Perforce・Mercurial などでは、WorktreeCreate と WorktreeRemove フックで作成と後片付けの処理を用意します。フックが git の既定の動作を置き換えるので、--worktree を使うとき .worktreeinclude は処理されません。ローカルの設定ファイルは、フックのスクリプトの中でコピーしてください。

次の WorktreeCreate フックは、標準入力の JSON から jq で worktree の名前を読み、SVN の作業コピーを新しくチェックアウトし、そのディレクトリのパスを出力します。Claude Code はそれをセッションの作業ディレクトリに使います。設定は settings.json に足します。

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

セッションの終了時の後片付けには、WorktreeRemove フックを組み合わせます。入力のスキーマと削除の例はフックのリファレンスにあります。WorktreeCreate フックがあると、git リポジトリの外でも /batch を動かせます。各 /batch のサブエージェントは、プロジェクトのバージョン管理のコマンドで変更を公開し、PR を開けないときは、何を公開したかを報告します。git リポジトリの外での /batch には v2.1.281 以降が要ります。

トラブルシューティング#

次のエラーは、worktree の作成・起動時の入室・再開した session の入室で出ます。

起動時に worktree へ入れない#

起動時に worktree のディレクトリへ入れないと、パスを示すエラーを出して終了コード 1 で終わります。WorktreeCreate フックが、作ったディレクトリ以外のものを出力した、または設定後にディレクトリが消されたときに起きます。

シンボリックリンクのパスで作成に失敗する#

.claude・.claude/worktrees・worktree のディレクトリ自体のいずれかがシンボリックリンクだと、Claude Code は worktree の作成を拒否し、リンクのパスをエラーで示します。リンクを消して再試行してください。v2.1.212 より前は、リポジトリにそのパスにコミット済みのシンボリックリンクがあると、作成がそれをたどってリポジトリの外にファイルを作ることがありました。

Claude Code が作った worktree で Git LFS のファイルがポインターになる#

git lfs install --local で Git LFS を設定していると、Claude Code が作る worktree には、実際のファイルではなく LFS のポインターファイルが入ります。--local は LFS のフィルターを、グローバルな git 設定でなくリポジトリ自身の .git/config に書くためです。素の git lfs install はグローバル設定に書くので影響しません。リポジトリ自身の設定で定義した、ほかのフィルタードライバーも同じです。

フィルタードライバーはシェルコマンドで、リポジトリに書き込めるもの（Claude を含む）が仕込める可能性があるため、Claude Code は worktree の作成時にリポジトリ自身のフィルタードライバーを飛ばします（v2.1.247 より前は動かしていました）。実際のファイルを得るには、worktree の中で git lfs pull を実行します。

まれに、次の4つのケースでは、worktree がまったく作られません。リポジトリの設定が定義するフィルタードライバーを判別できない、または無効にできない設定を見つけたときです。

Claude Code が worktree の使用を拒否する#

Refusing to use <path> as an isolation worktree で始まるエラーは、Claude Code が、そのディレクトリをセッションやサブエージェントの隔離チェックアウトとして採用する前に git の素性を確認して断ったことを示します。worktree の作成時・既存のものへの入室時・前回の実行のものの再利用時のいずれでも確認します。

多くの場合、残りのメッセージは、ディレクトリの git のメタデータがメインのチェックアウトに解決されると言っています（.git ファイルがメインのリポジトリ自身の .git を指す、core.worktree のリダイレクトで作業ツリーがメインのチェックアウトに解決される、など）。そのようなディレクトリでは、git reset --hard のような普通の git コマンドが worktree でなくメインのチェックアウトに作用してしまいます。読めない .git の項目があるときも拒否されます。

git のメタデータがまったくないディレクトリ（WorktreeCreate フックで作ったものなど）は、それを含む git リポジトリがない場合だけ通ります。フックがリポジトリの中にディレクトリを作ると、git はそれをそのリポジトリのチェックアウトに解決するので、git resolves its working tree to のメッセージで拒否されます。フックには、リポジトリの外にディレクトリを作らせてください。

拒否されたディレクトリは、作業が入っているかもしれないので、そのまま残されます。メッセージの終わりに合わせて対処します（再開のメッセージにだけ出る終わり方もあります）。

セッションが worktree の外で再開される#

対話的にセッションを再開して、Claude Code が worktree へ戻せないとき、次のメッセージのいずれかで伝えます。worktree との結びつきを解くときは、それをセッションのトランスクリプトに記録します。トランスクリプトの書き込みを止めている場合は、結びつきを解けなかったこと、あとの再開でもう一度確認することがメッセージに出ます。

-p の非対話モードと、Agent SDK が行う再開では、worktree が消えた場合を除くすべての拒否で、隔離なしで続けず、標準エラー出力のエラーで再開を止めます。--output-format stream-json では、拒否は標準出力にも、サブタイプ error_during_execution の result メッセージとして届き、errors 配列に同じ文面が入ります（v2.1.260 より前は、worktree の再開の拒否で result メッセージは出ませんでした）。メッセージの形は、対話のものと違います。

• Error: cannot resume into worktree <path>: ...This session was not started.：対話の表で Did not re-enter にあたる拒否。Claude Code は終了の前に worktree の結びつきを解き、エラーにそう書く。次にその会話を再開すると、worktree の隔離なしで現在のディレクトリで続く（v2.1.260 より前は、解いた結びつきを書かなかったため、同じ再開が毎回同じエラーで失敗した）。トランスクリプトの書き込みを止めていると解除を保存できず、同じコマンドがまた拒否されるとエラーに書かれ、--fork-session か新しい会話で、worktree なしで続ける方法が示される
• Error: could not verify worktree <path> for this resume, so the resume was aborted...：Could not verify にあたる
• Error: ...The worktree binding is kept.：Could not re-enter にあたる
• Notice: the worktree <path> for this session no longer exists...：消えた worktree。Claude Code はこれを出力し、対話の再開と同様にセッションを続ける

各エラーの末尾に埋まる拒否の理由は、対話の通知と共通なので、上の「拒否する」の節の項目に合わせて探せます。stream-json の result の startup_failure_reason は、could not verify worktree のエラーでは worktree_unverified、cannot resume into worktree と The worktree binding is kept のエラーでは worktree_resume_refused です。アプリはエラーの文面を照合せず、これで分岐できます（v2.1.274 より前は、result にこのフィールドはありませんでした）。