worktree を使用して並列セッションを実行する

​

worktree で Claude を開始する

claude --worktree feature-auth

​

worktree の環境をセットアップする

​

Claude に worktree の作成を依頼する

​

Claude に EnterWorktree ツールがない

• 対話セッション: claude --worktree を使用して worktree でセッションを開始します。
• バックグラウンドセッション: Claude Code は、セッションが EnterWorktree を呼び出すまで、メインチェックアウトでのバックグラウンドセッションの編集を拒否しますが、セッションにはそのツールがありません。次のいずれかを行うと、セッションが編集できるようになります。
  • claude --bg --worktree で開始する
  • worktree.bgIsolation を "none" に設定する
  • セッションを開始したディレクトリの下に git worktree add で作成した worktree で Claude に編集させる

​

worktree をクリーンアップする

• worktree がクリーンな場合: 名前のないセッションでは、Claude は worktree とそのブランチを自動的に削除します。名前付きセッションでは最初にプロンプトが表示されるため、後で使用するために worktree を保持できます
• worktree に作業が含まれている場合: Claude は worktree を保持するか削除するかを求めるプロンプトを表示します。保持するとディレクトリとブランチが保存されます。後で戻るには、Claude Code が終了時に出力する claude --worktree <name> --resume コマンドを実行します。削除すると worktree ディレクトリとそのブランチが、その中のすべての作業とともに削除されます
• 別のブランチがチェックアウトされている場合: worktree が自身のブランチ以外のブランチ上にあり、そのブランチに worktree の開始コミット以降のコミットがある場合、Claude は worktree を保持するか削除するかを求めるプロンプトを表示します。どちらを選択しても、その別のブランチとそのコミットは保持されます。削除すると、worktree ディレクトリと、Claude が worktree とともに作成した worktree 自身のブランチが削除されます
• worktree の状態を検証できない場合: Claude Code が worktree の変更をカウントできない、またはサブモジュールのチェックアウトを検査できない場合、worktree を自動的に削除するのではなくプロンプトを表示します。プロンプトには確認できなかった内容が示されます

​

worktree セッションを再開する

• 起動ディレクトリ: メインのチェックアウトまたはリポジトリの別のディレクトリから --resume で再開します。Claude Code は、.claude/worktrees/ の下に git で作成した worktree には、その内部から起動した場合でも再入します。その他の worktree の内部から起動した場合、Claude Code はそこからその worktree が安全であると確認できる場合にのみ再入します。独自のリポジトリである worktree、git メタデータを持たない worktree、または git worktree add で作成した worktree のサブディレクトリからの起動は拒否されるため、これらはメインのチェックアウトから起動してください。
• --fork-session: フォークされたセッションは Claude を起動したディレクトリで開始され、Claude Code は元のセッションの worktree に手を加えません。
• 削除された worktree: worktree ディレクトリが存在しなくなった場合、Claude Code は Claude を起動したディレクトリでセッションを再開します。worktree がなくなったことを通知し、セッションの worktree バインディングをクリアします。

​

Claude Code が分離を強制する仕組み

• ファイル編集: Claude Code は、メインチェックアウト内のパスを対象とする Edit、Write、または NotebookEdit をブロックします。メインチェックアウト内のファイルを変更するには、自分で編集するか、そこで対話型セッションを開始してください。
• コマンドの作業ディレクトリ: Claude Code は、作業ディレクトリがメインチェックアウトに解決される Bash、PowerShell、または Monitor コマンド、あるいは作業ディレクトリがメインチェックアウトの外にとどまることを検証できないコマンドをブロックします。
• Git のリダイレクト: Claude Code は、git をメインチェックアウトにリダイレクトする Bash または Monitor コマンドをブロックします。リダイレクトは、git -C、--git-dir、GIT_DIR または GIT_WORK_TREE 変数、あるいは git を実行する前のメインチェックアウトへの cd によって発生する可能性があります。
• コマンドの形式: Claude Code は、コマンドが実行する git が worktree 内にとどまることをコマンドテキストから検証できない場合、Bash または Monitor コマンドをブロックします。これは、たとえばコマンド名が実行時に計算される場合、構文を解析できない場合、または ${!name} や ${ command; } などの展開がテキストに明記されていないコマンドを実行する可能性がある場合に発生します。Claude Code は、拒否されたコマンドを単純な個別のコマンドに分割するなど、書き直す方法を Claude に伝えます。このチェックをオフにすることはできません。

​

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 内のチェックアウトされたサブモジュールに変更されたファイルや追跡されていないファイルがある、または Claude Code が worktree のサブモジュールを検査できない。このチェックには Claude Code v2.1.274 以降が必要です。
• worktree の作成もブロックする 4 つのケースのいずれかに該当する: Claude Code がリポジトリ設定で定義されているフィルタードライバーを特定できない、またはそこにオフにできない設定項目が見つかった。
• worktree が、バックグラウンドに送っていない --worktree セッションに属している（経過時間に関係なく）。
• git worktree add で worktree を自分で作成した（その後その中で --worktree <name> セッションを実行し、そのセッションをバックグラウンドに送った場合でも）。

​

worktree のロックと手動削除

​

worktree の作成をカスタマイズする

​

ベースブランチを選択する

• "fresh"（デフォルト）: リモート上のリポジトリのデフォルトブランチ（通常は main）からブランチするため、worktree はリモートと一致するクリーンなツリーから開始します。
• "head": 現在のローカル HEAD からブランチするため、worktree はプッシュされていないコミットと機能ブランチの状態を保持します。進行中の作業で動作する必要があるサブエージェントを分離する場合に使用します。worktree 内では、"head" はメインチェックアウトの HEAD ではなく、その worktree の HEAD に解決されます。

• 過去 24 時間にリポジトリがフェッチされていない場合、デフォルトブランチを 5 秒を上限としてフェッチし、フェッチが失敗した場合はローカルにキャッシュされたリファレンスを使用します。
• このフェッチはターミナルでの入力を待機しません。git または ssh がパスワード、鍵のパスフレーズ、または新しい SSH ホストの確認を求める場合も、失敗として扱われます。
• リモートが設定されていない場合、または origin/HEAD がローカルにキャッシュされておらずフェッチできない場合、worktree は現在のローカル HEAD にフォールバックします。

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

​

プルリクエストからブランチする

claude --worktree "#1234"

• github.com: pull/<number>/head をフェッチします
• gitlab.com: merge-requests/<number>/head をフェッチします
• GitHub Enterprise、セルフマネージド GitLab、またはその他のホスト: まず pull/<number>/head を試し、次に merge-requests/<number>/head を試します

​

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

.env
.env.local
config/secrets.json

​

worktree 名を再利用する

• コミットされていない変更または追跡されていないファイルがない。
• Claude Code が作成したブランチ上にまだある。
• 独自のコミットがない、またはプルリクエストやマージリクエストがマージされ、リモートブランチが削除されている。

• worktree がいずれかの条件を満たさない。
• Claude Code が worktree の状態を検証できない。
• worktree.baseRef が "head" である。
• 名前がプルリクエストまたはマージリクエストの参照である。

​

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

​

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

• リポジトリの .git ディレクトリ: worktree 内の git コマンドは、メインリポジトリの共有 .git ディレクトリに書き込みます。サンドボックスが有効な場合、git commit などのコマンドは worktree のルートで実行されるセッションで動作します。--worktree はこのルートでセッションを開始します。デフォルトでは、worktree のサブディレクトリで claude を実行すると、これらのコマンドは index.lock エラーで失敗します。
• プラグイン: メインチェックアウトからプロジェクトスコープでインストールされたプラグインは、同じリポジトリの worktree でも読み込まれるため、worktree ごとに再インストールする必要はありません。
• 権限の承認: worktree セッションで Bash コマンドに対して「はい、今後は確認しない」を選択すると、ルールはメインチェックアウトの .claude/settings.local.json に保存されます。このルールはメインチェックアウトとリポジトリの他のすべての worktree に適用され、worktree の削除後も残ります。 Windows や、Claude Code がリポジトリルートを使用しないその他のケースでは、ルールはその worktree に残ります。承認が保存される場所を参照してください。
• 追跡されていないスキル、エージェント、コマンド: worktree のチェックアウトのルートに .claude/skills ディレクトリがない場合（たとえば .claude/skills が gitignore されている場合）、Claude Code は worktree セッションでメインチェックアウトのプロジェクトスキルを読み込みます。独自の .claude/skills ディレクトリを持つ worktree では、そのコピーのみが読み込まれます。 同じ読み取りの引き継ぎは .claude/agents と .claude/commands にも適用されます。スキルについては、この引き継ぎには Claude Code v2.1.277 以降が必要です。

​

worktree を手動で管理する

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

git worktree add ../project-bugfix fix-issue-456

cd ../project-feature-a
claude

git worktree list

git worktree remove ../project-feature-a

​

非 git バージョン管理

{
  "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\"'"
          }
        ]
      }
    ]
  }
}

​

トラブルシューティング

​

Claude Code が起動時に worktree に入れない

​

シンボリックリンクされたパスで worktree の作成が失敗する

​

Claude Code が作成した worktree に置き換えられたオブジェクトの元の内容が含まれる

​

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

• Could not read the repository git config to neutralize filter drivers: Claude Code がリポジトリの .git/config を読み取れませんでした（たとえばそのファイルの権限が原因）。それを修正して再試行してください。
• The repository git config defines a filter driver whose name cannot be neutralized (contains "=" or a newline): .git/config 内のそのフィルタードライバーの名前を変更するか削除して、再試行してください。
• The repository git config has a conditional include (includeIf): .git/config 内の includeIf が取り込む設定をそのファイルに直接移動し、includeIf を削除して再試行してください。グローバル git 設定内の includeIf はこれをトリガーしません。
• Git was not run: the repository's own git config sets <key>: メッセージには、lfs.customtransfer.<name>.path や lfs.standalonetransferagent など、Git LFS に実行するプログラムを指定するキーが示されます。その設定が自分のものであれば、グローバル git 設定に移動します。心当たりがない場合は、信頼していないツールやチェックアウトが書き込んだ可能性があるため、リポジトリの git 設定から削除してください。リポジトリの設定からキーがなくなったら再試行してください。

​

パーシャルクローンで worktree の作成が失敗する

​

Can only use --worktree in a git repository

• バージョン管理を使用していないフォルダーでは、そこで git init を実行し、最初のコミットを作成してから再試行してください。
• 別のバージョン管理システムのチェックアウトでは、メッセージが提案するフックをセットアップしてください。
• ディレクトリで直接作業するには、--worktree を付けずに Claude を起動してください。

​

worktree ディレクトリが belongs to a different repository と表示される

​

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

• launch from the parent checkout または Run the resume from the project checkout と表示される: worktree 内から Claude Code を起動しました。代わりにメインチェックアウトから起動してください。worktree を再作成する必要はありません。
• it cannot be resumed or re-entered と表示される: このセッションには、起動した場所からその worktree を安全と確認できるものがありません。worktree を再作成してください。ディレクトリとその作業は手動回復のためにディスク上に残ります。worktree に親チェックアウトがある場合は、そこから再開することもできます。
• it contains the protected checkout と表示される: 拒否されたディレクトリは、ホームディレクトリなど、メインチェックアウトの親です。削除しないでください。WorktreeCreate フックが返すパスや EnterWorktree のターゲットなど、worktree のパスを変更して、worktree がチェックアウトを含まないようにしてください。
• the protected checkout <path> has a .git entry that could not be examined または has git metadata that could not be resolved と表示される: 問題は worktree ではなくメインチェックアウトの git メタデータにあります。worktree を削除しないでください。また、メッセージ末尾の worktree を再作成するようにというアドバイスは、これら 2 つの末尾には当てはまらないため無視してください。メインチェックアウトを修復し（たとえば .git に対する権限の問題や git の dubious ownership による拒否）、再試行してください。 v2.1.302 より前は、git 2.56 以降を使用している場合、the protected checkout の後の <path> に孤立した .git ファイルがあるときにも、could not be resolved という末尾が表示されていました。ここでいう孤立とは、そのファイルの gitdir: 行にあるパスが有効な git リポジトリにつながらないことを意味します。回復するには、Claude Code を更新して再試行してください。その gitdir: パスがもう存在しない場合は、.git ファイルを削除して再試行することもできます。
• its recorded path has a network spelling と表示される: Claude Code はネットワークパスにある worktree へ再開することはありません。ローカルパスに worktree を再作成してください。
• その他の末尾: メッセージには、core.worktree リダイレクトの削除や worktree の再作成など、問題とその修正方法が示されています。それに従ってください。git ID を検証できなかったというメッセージが表示されたディレクトリを削除する前に、worktree のパス内のシンボリックリンクや git 自体の実行失敗など、示された原因に先に対処してください。ディレクトリが正常である可能性があるためです。再作成する場合は、先に古いディレクトリから必要な変更を回収してください。古いディレクトリはディスク上に残ります。

​

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

• 表で Did not re-enter として示される拒否の場合は Error: cannot resume into worktree <path>: ...This session was not started.。Claude Code は終了前に worktree バインディングをクリアし、エラーにもそのことが示されます。次に会話を再開すると、セッションは worktree 分離なしで現在のディレクトリで続行されます。v2.1.260 より前は、Claude Code はクリアされたバインディングを書き込まなかったため、同じ再開を再試行するたびに同じエラーで失敗していました。 トランスクリプトの書き込みを抑制している場合、クリアを保存できません。その場合、エラーには同じコマンドが再び拒否されることが示され、worktree なしで続行する方法として --fork-session と新しい会話の開始が挙げられます。
• Could not verify の場合は Error: could not verify worktree <path> for this resume, so the resume was aborted...
• Could not re-enter の場合は Error: ...The worktree binding is kept.
• worktree が存在しない場合は Notice: the worktree <path> for this session no longer exists...。Claude Code はこれを出力し、対話的な再開と同様にセッションを続行します

​

関連項目

• サブエージェント: セッション内の分離されたエージェントに作業を委任する
• セッション間メッセージング: worktree 内のセッション同士で調査結果を受け渡せるようにする
• エージェントチーム: 複数の Claude セッションを自動的に調整する
• セッションを管理する: 会話に名前を付け、再開し、切り替える
• デスクトップセッションを専用の worktree で実行する: デスクトップアプリの worktree でサポートされるセッション