Claude CodeのGit worktree：並行セッション

Ailootの利用に関する実用情報はドキュメントにあります。

Claude CodeのGit worktreeとは#

同じフォルダーで複数のエージェントを並行して起動することが、2026年のスピードでvibe-codingを行うときに生じる基本的な問題です。AIエージェントは、人が誰が何に触れているのか把握するよりも速くコードを書きます。ファイルを分離せず、同じディレクトリでClaude Codeのセッションを2つ並行して起動すると、一方のセッションがもう一方の作業を上書きしてしまいます。

Git worktreeは、この問題をファイルシステムのレベルで解決します。作業するメインディレクトリが1つあります。コマンド claude --worktree feature-auth は、別ブランチに .claude/worktrees/feature-auth/ フォルダを作成し、その中でClaude Codeを起動します。ファイルは分離されています。一方のセッションでの変更は、明示的にマージするまで、もう一方のセッションからは見えません。

Anthropicの公式ドキュメントでは、次のように説明されています。

自分で振り返る目安として、誰かの作業が半分混ざったコミットを受け取ったことがあるなら、worktreeが必要です。

Git worktreeと通常のブランチの違い#

標準的なGitの流れでは、main ブランチにいるときに git checkout feature-x を実行すると、Gitは作業コピーのファイルを上書きします。package.json が書き換わるため、実行中の npm run dev が動かなくなります。未コミットの変更をstashして、IDEの再インデックスが終わるのを待ちます。元に戻ると、またすべてが上書きされるので、もう一度stashしてpopしなければなりません。

Git worktreeなら別の方法があります。ブランチ間で1つのフォルダを切り替える代わりに、別ブランチ用の2つ目のフォルダを作成します。コマンド git worktree add ../project-feature-x feature-x は、ブランチ feature-x のファイルを含むディレクトリ ../project-feature-x/ を作成します。main は元のフォルダに残り、開発サーバーも動き続けます。

以前はClaude Codeでworktreeモードを使うには、手動で git worktree add を実行し、次に cd してから claude を起動する必要があり、ターミナルごとに繰り返していました。--worktree フラグ（別名 -w）なら、この3つを1つのコマンドで実行できます。

最初の並行セッションを起動する：--worktree フラグ#

最小限の例です。最初のターミナルをプロジェクトのルートで開きます。

claude --worktree feature-auth

Claude Codeは次の3つを行います。

1. origin/HEAD（通常はデフォルトブランチ）のスナップショットを使って .claude/worktrees/feature-auth/ を作成します。
2. 新しい worktree-feature-auth ブランチを作成します。
3. このフォルダでセッションを起動します。

同じリポジトリのルートフォルダで2つ目のターミナルを開きます。

claude --worktree bugfix-123

これで完了です。Claude Codeのセッションが2つ、ディスク上の別々のファイル、別々のGitブランチで動きます。片方で認証機能を書き、もう片方で失敗しているテストを修正しても、物理的に互いの作業を妨げることはありません。

名前を入力したくなければ、Claudeが考えてくれます。

claude --worktree
# → .claude/worktrees/bright-running-fox/ のようなものを作成

Git初心者向けのヒント：.claude/worktrees/ を .gitignore に追加してください。そうしないと、メインフォルダで git status を実行したとき、すべてのworktreeの内容が未追跡ファイルとして表示されます。

# .gitignore
.claude/worktrees/

避けるべき落とし穴：新しいディレクトリで初めて --worktree を起動する前に、フラグなしの通常の claude でそのディレクトリを開き、ワークスペースの信頼確認ダイアログを承認してください。承認しないと、フラグは「信頼が承認されていない」というエラーで失敗します。ヘッドレスモード用の -p と組み合わせた場合も同様です。

worktreeの場所と見つけ方#

デフォルトの場所は固定されており、リポジトリのルートにある .claude/worktrees/<value>/ です。プロジェクトが ~/dev/my-app/ にあるなら、feature-auth worktreeは ~/dev/my-app/.claude/worktrees/feature-auth/ に置かれます。

リポジトリの外にworktreeを置きたい場合など、標準的でない構成には WorktreeCreate フックがあります。詳しくは後述のSVNとMercurialに関するセクションで説明します。

Claudeの1つのセッション内で、別の既存worktreeに切り替えられます。チャットで「.claude/worktrees/bugfix-123 に切り替えて」と伝えるだけで、Claudeが EnterWorktree ツールを呼び出します。現在のフォルダには手を加えず、そのまま残せます。同じ方法で戻れます。

標準のGitコマンドを使うと、メインのworktreeと手動で作成したworktreeを含む、すべてのworktreeの一覧が表示されます。

git worktree list

出力は次のようになります。

/home/user/dev/my-app                  abc1234 [main]
/home/user/dev/my-app/.claude/worktrees/feature-auth  def5678 [worktree-feature-auth]
/home/user/dev/my-app/.claude/worktrees/bugfix-123    9876fed [worktree-bugfix-123]

.env とシークレットをコピーする：.worktreeinclude ファイル#

--worktree で新しいフォルダを作ると、Gitにコミットされているものだけが入ります。APIキーを含む .env やローカル設定の .env.local は .gitignore 対象なので、worktreeには入りません。そのため、最初の npm run dev は「MISSING DATABASE_URL」で失敗します。

手作業での解決策は、--worktree を実行するたびに .env をコピーすることです。一度はうまくいきますが、やがて忘れてしまいます。Anthropicの解決策は、プロジェクトのルートに .worktreeinclude ファイルを置き、Gitで無視されるファイルのうち、新しいworktreeごとに自動コピーするものを列挙することです。

リポジトリのルートに .worktreeinclude ファイルを作成します。

.env
.env.local
config/secrets.json

構文は .gitignore と同じです。globパターンも使えます。

.env*
*.local
config/*.json
.vscode/settings.json

Anthropicは、事故を防ぐための明確なルールを示しています。

つまり、.worktreeinclude を使って package.json を誤ってコピーすることはありません。これは .gitignore 対象ではないからです。どんなパターンを指定しても安全です。

同じ .worktreeinclude が3つのモードで使われます。手動の --worktree、サブエージェント用の自動worktree（後述）、Claudeデスクトップアプリのセッションです。

コードレビュー用にプルリクエストからworktreeを作成する#

よくあるコードレビューの場面を考えてみましょう。同僚からPRが届き、コードを確認してテストを実行し、コメントを残す必要があります。通常の git checkout pull/1234/head では、作業コピーをまた切り替えることになり、進行中のセッションに支障が出ます。

--worktree フラグを使えば、コマンド1つで済みます。

claude --worktree "#1234"

何が起きるかというと、Claude Codeは git fetch origin pull/1234/head を実行し、.claude/worktrees/pr-1234/ にworktreeを作成して、PRブランチをチェックアウトします。セッションが始まります。すぐに「差分を読み、テストを実行し、論理的な誤りを探して」と頼めます。その間、main 上のメインセッションは動き続けます。

完全なプルリクエストURLを指定する書き方もあります。

claude --worktree https://github.com/OWNER/REPO/pull/1234

実際のプロジェクトでは、claude --worktree "#N" と自作のコードレビュアー・サブエージェントを組み合わせると、1〜2分で自動レビューができます。バックグラウンドで起動し、メインウィンドウで作業を続け、結果は claude agents から確認します。

ベースブランチ：fresh または head の worktree.baseRef#

デフォルトでは、新しいworktreeはすべて origin/HEAD から開始します。CIで確認される内容と一致することが保証された、クリーンな開始状態になるのが利点です。一方、現在のブランチに未コミットの変更や、リモートより先に進んだローカルコミットがいくつかあっても、それらは新しいworktreeに含まれません。

現在のローカルHEADコミットからworktreeを始めるには、.claude/settings.jsonかグローバル設定へ次を追加します。

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

これでclaude --worktree experimental-featureは現在のローカルHEADから始まります。機能にすでに未プッシュのローカルコミットがある場合に便利です。未コミットの追跡済み編集は含みません。必要なら保全して明示的に移行し、移行先の差分を確認してください。これは無視対象のローカルファイルを扱う.worktreeincludeとは別です。

この設定で指定できる値は正確に2つです。"fresh"（origin/HEAD）と "head"（ローカルのHEAD）です。"feature-branch" やコミットハッシュのような任意のrefは指定できません。選択肢の組み合わせが爆発的に増えるのを防ぐため、意図的に制限されています。

サブエージェントを自動的に分離する：isolation: worktree#

Claudeに「サブエージェントを3つ起動して。1つ目はデータベース、2つ目はAPI、3つ目はテストを調べて」と伝えると、デフォルトでは3つともあなたの作業コピーで動きます。2つでも同じファイルに同時に書き込めば、競合します。解決策は、それぞれに専用のworktreeを自動的に割り当てることです。

方法1：口頭で頼む。会話の中でClaudeに次のように伝えます。

エージェントにはworktreeを使ってください。

Claudeは、このセッションで以降に起動するすべてのサブエージェントに分離を適用します。

方法2：サブエージェント自体に明示的に設定します。サブエージェントのファイル（例：.claude/agents/code-reviewer.md）のfrontmatterにフィールドを追加します。

---
name: code-reviewer
description: Reads the diff and writes code review comments
isolation: worktree
---

You're a meticulous reviewer. Read the diff and look for logic errors...

これで、このサブエージェントを起動するたびに .claude/worktrees/ 内に一時worktreeが作られます。サブエージェントが何も書き込まなければ、終了時にフォルダが自動削除されます。未コミットの変更がある場合、Claudeは残すか削除するかを確認します。

サブエージェント用worktreeのベースブランチは、--worktree と同じです。デフォルトでは origin/HEAD、worktree.baseRef: head を設定している場合はローカルの HEAD です。

判断マトリックス：worktree、/bg、subagent、Agent View#

典型的な組み合わせ：

• 「2つの機能を手動で並行開発」 — 2つのターミナルで、それぞれ claude --worktree を実行します。最もシンプルなケースです。
• 「夜通しリファクタリングを実行して、アプリを閉じる」 — /bg と /goal に完了条件を設定します。セッションはウィンドウを閉じても独立して動きます。
• 「1つのプロンプトで3つの調査を並行実行」 — isolation: worktree を指定したサブエージェントを3つ起動します。それぞれが独自のサンドボックスで動きます。
• 「今、何が実行中？」 — claude agents を使います。「実行中」「ブロック中」「完了」のフィルターがある、全セッションのダッシュボードです。

worktree利用時の5つの落とし穴#

1. worktreeを起動したら .env がなく、何も動かない。 最もよくある問題です。worktreeはGitで無視されるファイルがない新しいチェックアウトです。解決策は、worktreeモードを設定するときにすぐ .worktreeinclude ファイルを追加し、.env* と必要なローカル設定を指定することです。このファイルが .claude/ ではなくリポジトリのルートにあることを確認してください。

2. メインブランチに切り替えようとしてルートで cd を実行したら、worktreeの未コミット変更を失った。 ルートフォルダとworktreeは異なる作業コピーです。cd で戻っても、worktreeの変更はそのまま残っていて、どこにも行っていません。ただし、worktreeにいると思い込んでメインフォルダで git stash を実行すると、stashは予想していたブランチではなく、メインブランチに作成されます。

3. セッションを5つ並行して起動し、それぞれ何をしているのか思い出せない。 Anthropicのドキュメントは、ほとんどの開発者は認知的に2〜3個を超えるセッションを扱えないと明示的に警告しています。過負荷の兆候は、Agent Viewを開いても各エージェントが何をしているのかすぐに言えないことです。同時に実行するセッションは2つに制限しましょう。それ以上必要なタスクは、手動ではなく /goal とサブエージェントで調整すべきです。

4. -p（ヘッドレス）で起動したworktreeは自動クリーンアップされない。 コマンド claude --worktree feature-x -p "do thing" では対話的な終了プロンプトが表示されないため、Claudeが「worktreeを削除しますか？」と尋ねるタイミングがありません。こうしたworktreeは蓄積します。手動でクリーンアップしてください。git worktree remove .claude/worktrees/feature-x を実行します。または、7日より古いものを削除するcronスクリプトを使います。

5. 新しいフォルダで信頼確認ダイアログが表示される。 初めてリポジトリを開いてすぐに claude --worktree を実行すると、コマンドは失敗します。フラグなしで claude を実行し、ワークスペースの信頼を承認して終了してください。その後は --worktree が動作します。これは、ユーザーの同意なしにClaudeが他人のプロジェクトへアクセスしないようにするための意図的な仕組みです。

クリーンアップ：自動削除されるもの#

クリーンアップの仕組みは、worktreeで何をしたか、セッションをどう開始したかによって異なります。Anthropicのドキュメントには、3つのシナリオが記載されています。

シナリオ1：worktreeに入り、何もせず終了すると、worktreeは削除されます。

シナリオ2：作業をしてコミットしなかった場合、終了時にClaudeが「残すか、削除するか」を確認します。「残す」を選ぶと、後で使えるようにフォルダとブランチが保存されます。「削除」を選ぶと、未コミットの変更と新しいコミットも含めてディレクトリが削除されます。これは取り消せない操作です。習慣で「削除」をクリックしないでください。

シナリオ3：-p（ヘッドレス）で起動し、コマンドが完了して終了した場合、worktreeは残ります。手動でクリーンアップしてください。

git worktree remove .claude/worktrees/feature-x

さらに、サブエージェントと /bg のセッションから作られたworktreeは、cleanupPeriodDays 日（通常のデフォルトは30日）より古く、かつ保存されていない作業がない場合、バックグラウンドのクリーンアップによって自動削除されます。--worktree で作成したworktreeは自動クリーンアップの対象ではありません。管理はあなたの責任です。

SVN、Perforce、Mercurialでの代替方法：WorktreeCreate フック#

リポジトリがSubversionやMercurialを使っている場合、--worktree フラグはそのままでは動きません。Anthropicは、2つのフックを使った拡張方法を提供しています。WorktreeCreate は分離されたコピーを作成し、WorktreeRemove はそれを削除します。

公式ドキュメントにあるSVNフックの例です。

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

フックは標準入力からworktree名（{ "name": "feature-auth" }）を読み込み、事前に決めたディレクトリに svn checkout を実行し、パスを標準出力に出力します。Claude Codeはそのパスを、新しいセッションの作業ディレクトリとして使用します。

重要な注意点として、独自のフックを使う場合、.worktreeinclude は使用されません。新しいフォルダで .env などGitで無視されるファイルが必要なら、フックスクリプトの中でコピーしてください。

次に読む内容：並行処理に関する3つの仕組み#

worktreeはファイルを分離します。/bg はコンテキストを分離します。サブエージェントはタスクを分離します。それぞれの仕組みは単独で1つの問題を解決します。組み合わせることで、認知的に破綻することなく3〜5個のタスクに並行して取り組めます。これは、2026年の高度なvibe-codingを支えるスキルセットです。

このトピックは、次の3つの関連テーマへ自然につながります。/goal と Agent Viewを使って自律エージェントを設定する方法、自分のタスクに合わせたサブエージェントの作り方、Dynamic Workflowsを通じて数百のエージェントを起動する方法。

Ailootを開く。