中小DXラボ のツール

Claude Code を worktree で並行して動かす方法と注意点

公開: ・ 中小DXラボ ・ 内容は執筆時点(2026年10月)の公式ドキュメントなどの出典にもとづきます(各節の末尾に出典を記載)

結論

  • --worktree(または -w)に名前を付けて起動すると、専用のブランチとディレクトリで隔離されたセッションが始まります。別のターミナルで名前を変えて実行すれば並行作業になります。
  • worktree は新しいチェックアウトなので、依存関係のインストールなど環境の初期化が必要です。.env のような gitignore 対象のファイルは .worktreeinclude ファイルで引き継げます。
  • 終了時の後片付け、-p 実行時の扱い、cp などを防げない隔離の限界には条件があります。社内に配る前に確認してください。

worktree でできること:セッションを分けて並行作業する

Claude Code(Anthropic 社が提供する、ターミナルで動く AI コーディングエージェント)では、worktree(同じリポジトリから作る、作業用の別ディレクトリ)を使って複数のセッションを並行して動かせます。本記事は執筆時点(2026年10月)の公式ドキュメントに基づきます。

公式ドキュメントによると、--worktree または -w に名前を付けて渡すと、隔離された worktree を作り、その中で Claude を起動します。既定では、リポジトリのルートの .claude/worktrees/<name>/ の下に、worktree-<name> という新しいブランチで作られます。

claude --worktree feature-auth

別のターミナルで違う名前を付けて同じコマンドを実行すると、2つ目の隔離されたセッションが始まります。名前を省略すると、bright-running-fox のような名前を Claude が生成します。

出典: Run parallel sessions with worktrees

起動前の設定と注意点

公式ドキュメントでは、対話実行には workspace trust が必要とされています。初めて使うディレクトリでは、先に claude を一度実行して trust ダイアログを承認してください。承認していないと --worktree はエラーで終了します。-p の非対話実行は trust チェックを省略するため、claude -p --worktree はそのまま進みます。

.claude/worktrees/ を .gitignore に追加すると、worktree の中身がメインのチェックアウトで未追跡ファイルとして表示されません。

環境の初期化

worktree は新しいチェックアウトです。Claude に依存関係のインストールを頼むか、.claude/worktrees/ 配下の worktree ディレクトリでプロジェクトのセットアップを実行します。.env のような gitignore 対象のファイルを新しい worktree に自動で持ち込むには、.worktreeinclude ファイルを追加します。書き方は公式ドキュメントで確認してください。

セッション中に頼む場合

セッション中に「work in a worktree」と頼むと、EnterWorktree ツールで作成されます。リポジトリの .claude/worktrees/ の外のパスに入るときは、作業ディレクトリや書き込み権限、CLAUDE.md などの設定が移るため、承認を求められます。この確認は permission rule や「don't ask again」では止められず、bypassPermissions モードだけがスキップします。v2.1.206 より前は、確認なしで入れました。

出典: Run parallel sessions with worktrees

終了時の後片付けと削除の注意

対話セッションを終えるとき、Claude は削除で失われる作業(変更・未追跡ファイル、サブモジュール内の未コミットの作業、新しいコミット)がないか確認します。これは git で作られた worktree が対象です。

  • クリーンな場合:名前なしのセッションは worktree とブランチを自動で削除します。名前付きのセッションは先に確認があります。
  • 作業が残っている場合:保持か削除かを聞かれます。保持するとディレクトリとブランチが残り、終了時に表示される claude --worktree <name> --resume で戻れます。削除すると作業ごと消えます。
  • 状態を確認できない場合:自動では削除せず、確認できなかった内容を示して聞かれます。

-p の非対話実行には終了時の確認がなく、worktree は片付けられません。作成時のロックも、後のセッションが解除するまで残ります。削除は git worktree remove で行い、ロックで拒否されたら先に git worktree unlock を実行します。

Windows では、worktree 内のリンク(NTFS junction やディレクトリ symlink)はリンクだけが削除され、指す先は残ります。v2.1.205 より前は、サブディレクトリにリンクがあると指す先が消える場合がありました。

出典: Run parallel sessions with worktrees

隔離のチェックと限界

隔離された worktree のセッションでは、次の4つのチェックでツール呼び出しがブロックされます。--worktree での起動、EnterWorktree、再開のどれでも、また Claude が起動するサブエージェントにも同じです。

  • ファイル編集:Edit、Write、NotebookEdit がメインのチェックアウトのパスを対象にする場合。
  • コマンドの作業ディレクトリ:Bash、PowerShell、Monitor のコマンドの作業ディレクトリがメインのチェックアウトになる、または外にとどまると確認できない場合。
  • git のリダイレクト:git -C、--git-dir、GIT_DIR や GIT_WORK_TREE の変数、cd で git をメインのチェックアウトへ向ける Bash や Monitor のコマンド。
  • コマンドの形:git が worktree 内に収まると文面から確認できない Bash や Monitor のコマンド。このチェックはオフにできません。

ただし、これらはシェルコマンドが書き込むファイルを追跡しません。git を実行せずメインのチェックアウトへ書き込む cp やシェルのリダイレクトは拒否されず、通常のシェルコマンドとして permissions と sandboxing の設定で扱われます。PowerShell に適用されるのは作業ディレクトリのチェックだけです。

出典: Run parallel sessions with worktrees

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

worktree は独自のファイルとブランチを持ちますが、次を共有します。--worktree でも git worktree add でも同じです。

  • .git ディレクトリ:共有の .git に書き込み、sandboxing も許可するため、sandbox 有効でも git commit が使えます。
  • プラグイン:メインのチェックアウトでプロジェクトスコープに入れたプラグインは、同じリポジトリの worktree でも読み込まれます。v2.1.200 以降が必要です。
  • 許可の承認:worktree で Bash コマンドに「Yes, and don't ask again」を選ぶと、メインのチェックアウトの .claude/settings.local.json に保存され、他の worktree にも適用されます。Windows などリポジトリルートを使わない場合は、その worktree にとどまります。v2.1.211 より前は worktree 内に保存され、削除で失われました。
  • 未追跡のスキル・エージェント・コマンド:worktree のルートに .claude/skills がないと、メインのプロジェクトスキルを読み込みます。スキルについては v2.1.277 以降が必要です。

hook を使う場合

${CLAUDE_PROJECT_DIR} は、worktree に入ってもセッションを始めたプロジェクトルートのままです。worktree のパスが必要な hook は、入力 JSON の cwd を読みます。デスクトップアプリから始めた worktree セッションでは、設定や hook などをメインのチェックアウトのルートから読み、CLAUDE.md と .claude/rules/ は worktree から読みます。

出典: Run parallel sessions with worktrees

よくある質問

worktree のセッションが、メインのチェックアウトのファイルを書き換えることはありませんか?

公式ドキュメントによると、Edit、Write、NotebookEdit でメインのチェックアウトのパスを対象にする操作はブロックされます。ただし、git を実行せずに書き込む cp やシェルのリダイレクトはこのチェックでは拒否されません。permissions と sandboxing の設定で扱われるため、その設定の確認が必要です。

出典: Run parallel sessions with worktrees

-p で起動した worktree は、終了時に自動で削除されますか?

されません。公式ドキュメントによると、-p の非対話実行には終了時の確認がなく、worktree は片付けられません。削除するには git worktree remove を実行し、ロックで拒否された場合は先に git worktree unlock を実行します。

出典: Run parallel sessions with worktrees

.env のような gitignore 対象のファイルを、新しい worktree に持ち込めますか?

公式ドキュメントでは、.worktreeinclude ファイルを追加すると、新しい worktree に自動で持ち込めるとされています。書き方の詳細は出典に記載がないため、公式ドキュメントで確認してください。

出典: Run parallel sessions with worktrees

関連する無料ツール

Claude Code CLAUDE.md テンプレート生成: 用途と守ってほしいことを選ぶと、短い CLAUDE.md のひな形を出力します。最初の数行を決めるときに使えます。

参考(執筆時点)

この記事は、上の出典の内容を中小DXラボが要約・再構成したものです。仕様は変わることがあります。社内で使う・配る前に、公式ドキュメントで最新の情報を確認してください。