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

並列 Claude Code セッションを個別の git worktree に分離して、変更が衝突しないようにします。--worktree フラグ、subagent の分離、.worktreeinclude、クリーンアップ、および非 git VCS フックについて説明します。

git worktree は、独自のファイルとブランチを持つ別の作業ディレクトリであり、メインのチェックアウトと同じリポジトリ履歴とリモートを共有します。各 Claude Code セッションを独自の worktree で実行すると、1 つのセッションでの編集は別のセッションのファイルに触れることがないため、Claude が 1 つのターミナルで機能を構築しながら、2 番目のターミナルでバグを修正できます。

このページでは、CLI での worktree の分離について説明します。以下のすべての内容は git リポジトリを想定しています。その他のバージョン管理システムについては、非 git バージョン管理 を参照してください。デスクトップアプリ は、新しいセッションごとに自動的に worktree を作成します。

Worktree は Claude を並列で実行するいくつかの方法の 1 つです。これらは、ファイル編集を分離しますが、subagent と agent team は作業自体を調整します。アプローチを比較するには Claude を並列で実行する を参照するか、worktree と subagent を一緒に使用するには worktree で subagent を分離する にスキップしてください。

worktree で Claude を開始する

--worktree または -w を渡して、分離された worktree を作成し、その中で Claude を開始します。デフォルトでは、worktree はリポジトリルートの .claude/worktrees/<value>/ の下に作成され、worktree-<value> という名前の新しいブランチ上に作成されます。

claude --worktree feature-auth

Worktree を別の場所に配置するには、WorktreeCreate フック を設定します。別のターミナルで異なる名前を使用してコマンドを再度実行して、2 番目の分離されたセッションを開始します。

claude --worktree bugfix-123

名前を省略すると、Claude は bright-running-fox などの名前を生成します。

claude --worktree

セッション中に Claude に「worktree で作業する」と指示することもでき、EnterWorktree ツールを使用して作成します。Worktree に入ると、Claude は .claude/worktrees/ の下の別の worktree に EnterWorktree をターゲットパスで呼び出すことで直接切り替えることができます。前の worktree はディスク上に変更されずに残ります。

初めてディレクトリで --worktree をインタラクティブに使用する前に、そのディレクトリで claude を 1 回実行してワークスペース信頼ダイアログを受け入れてください。信頼がまだ受け入れられていない場合、--worktree はエラーで終了し、最初にディレクトリで claude を実行するよう求めるプロンプトが表示されます。-p を使用した非インタラクティブ実行は信頼チェックをスキップするため、claude -p --worktree はそれなしで進行します。

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

Worktree はリポジトリのデフォルトブランチ origin/HEAD からブランチするため、リモートと一致するクリーンなツリーから開始します。リモートが設定されていない場合、またはフェッチが失敗した場合、worktree は現在のローカル HEAD にフォールバックします。代わりにローカル HEAD から常にブランチするには、設定 で worktree.baseRef を "head" に設定します。baseRef を "head" に設定すると、新しい worktree はプッシュされていないコミットと機能ブランチの状態を保持します。これは、進行中の作業で動作する必要がある subagent を分離する場合に便利です。この設定は "fresh" または "head" のみを受け入れ、任意の git ref は受け入れません。

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

特定のプルリクエストからブランチするには、# が付いた PR 番号、または完全な GitHub プルリクエスト URL を渡します。Claude Code は origin から pull/<number>/head をフェッチし、.claude/worktrees/pr-<number> に worktree を作成します。

claude --worktree "#1234"

Worktree の作成方法を完全に制御するには、WorktreeCreate フック を設定します。これはデフォルトの git worktree ロジックを完全に置き換えます。

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

Worktree は新しいチェックアウトなので、メインリポジトリの .env や .env.local などの追跡されていないファイルは存在しません。Claude が worktree を作成するときに自動的にコピーするには、プロジェクトルートに .worktreeinclude ファイルを追加します。

このファイルは .gitignore 構文を使用します。パターンに一致し、かつ gitignore されているファイルのみがコピーされるため、追跡されているファイルは決して複製されません。

この .worktreeinclude は 2 つの env ファイルと 1 つのシークレット設定を各新しい worktree にコピーします。

.env
.env.local
config/secrets.json

これは --worktree で作成された worktree、subagent worktree、およびデスクトップアプリ の並列セッションに適用されます。

worktree で subagent を分離する

Subagent は独自の worktree で実行できるため、並列編集は競合しません。Claude に「エージェント用に worktree を使用する」と指示するか、カスタム subagent にフロントマターに isolation: worktree を追加して永続的に設定します。各 subagent は一時的な worktree を取得し、subagent が変更なしで完了すると自動的に削除されます。

Subagent worktree は --worktree と同じベースブランチを使用するため、worktree.baseRef が "head" に設定されていない限り、リポジトリのデフォルトブランチから分岐します。

worktree をクリーンアップする

Worktree セッションを終了すると、クリーンアップは変更を加えたかどうかによって異なります。

• コミットされていない変更なし、追跡されていないファイルなし、新しいコミットなし: worktree とそのブランチは自動的に削除されます。セッションに名前がある場合、Claude は代わりにプロンプトを表示するため、後で使用するために worktree を保持できます
• コミットされていない変更、追跡されていないファイル、または新しいコミットが存在する: Claude は worktree を保持するか削除するかを求めるプロンプトを表示します。保持するとディレクトリとブランチが保存されるため、後で戻ることができます。削除すると worktree ディレクトリとそのブランチが削除され、すべてのコミットされていない変更、追跡されていないファイル、およびコミットが破棄されます
• 非対話的な実行: -p と共に --worktree で作成された worktree は、終了プロンプトがないため自動的にクリーンアップされません。git worktree remove で削除します

Claude が subagent およびバックグラウンドセッション用に作成した worktree は、cleanupPeriodDays設定より古い場合、コミットされていない変更、追跡されていないファイル、およびプッシュされていないコミットがない場合、自動的に削除されます。--worktree で作成した worktree は、このスイープによって削除されることはありません。

エージェントが実行中の間、Claude は worktree に対して git worktree lock を実行するため、同時実行クリーンアップがそれを削除することはできません。ロックはエージェントが完了すると解放されます。スイープが保持する worktree をクリーンアップするには、git worktree remove を実行し、worktree にコミットされていない変更または追跡されていないファイルがある場合は --force を追加します。

worktree を手動で管理する

Worktree の場所とブランチ設定を完全に制御するには、Git を直接使用して worktree を作成します。これは特定の既存ブランチをチェックアウトするか、worktree をリポジトリの外に配置する必要がある場合に便利です。

新しいブランチに worktree を作成します。

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

既存のブランチから worktree を作成します。

git worktree add ../project-bugfix bugfix-123

Worktree で Claude を開始します。

cd ../project-feature-a && claude

Worktree をリストします。

git worktree list

完了したら削除します。

git worktree remove ../project-feature-a

完全なコマンドリファレンスについては、Git worktree ドキュメント を参照してください。各新しい worktree で開発環境を初期化することを忘れないでください。依存関係をインストールし、仮想環境をセットアップするか、プロジェクトのセットアップが必要なものを実行します。

非 git バージョン管理

Worktree の分離はデフォルトで git を使用します。SVN、Perforce、Mercurial、またはその他のシステムの場合、WorktreeCreate および WorktreeRemove フック を設定して、カスタム作成およびクリーンアップロジックを提供します。フックはデフォルトの git 動作を置き換えるため、--worktree を使用する場合、.worktreeinclude は処理されません。フックスクリプト内でローカル設定ファイルをコピーしてください。

この WorktreeCreate フックは stdin から worktree 名を読み取り、新しい SVN 作業コピーをチェックアウトし、ディレクトリパスを出力して Claude Code がセッションの作業ディレクトリとして使用できるようにします。

{
  "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 フックとペアにします。入力スキーマと削除例については、フックリファレンス を参照してください。

関連項目

Worktree はファイルの分離を処理します。以下の関連ページでは、これらの分離されたチェックアウトに作業を委任し、作成したセッション間を切り替える方法について説明しています。

• Subagent: セッション内の分離されたエージェントに作業を委任する
• Agent team: 複数の Claude セッションを自動的に調整する
• セッションを管理する: 会話に名前を付け、再開し、切り替える
• デスクトップ並列セッション: デスクトップアプリの worktree でサポートされるセッション