Worktrees (ワークツリー)

セッションごとに編集用のファイルのコピーが分かれるため、一方のセッションで機能を作り、別のセッションでバグを直すといった並行作業に使えます。ターミナルから --worktree フラグで起動できるほか、セッションの途中で Claude に「work in a worktree」と依頼して作成することもできます。

Worktrees は、Claude Code のセッションを git worktree 単位で分け、セッションごとに別々のファイルのコピーを編集させる機能です。

• ターミナルでは --worktree (-w) で起動します。既定の作成場所はリポジトリのルートの .claude/worktrees/<name>/ で、ブランチ名は worktree-<name> です。
• --worktree に渡した名前の worktree がすでにあれば、新しく作らずにその worktree を開きます。
• セッションの途中で「work in a worktree」と依頼すると、Claude が EnterWorktree ツールで worktree を作成します。リポジトリの .claude/worktrees/ の外のパスに入る場合は、先に承認を求めます。
• worktree の中で終了せずに終わったセッションを再開すると、セッションはその worktree に戻ります。
• メインのチェックアウトからプロジェクトスコープでインストールしたプラグインは、同じリポジトリの worktree でも読み込まれます。

セッションが worktree に分離されている間、メインのチェックアウト内のパスを対象とする Edit、Write、NotebookEdit の呼び出しはブロックされます。

一方で、この分離のチェックはシェルコマンドが書き込むファイルを追跡しません。そのため、cp やシェルのリダイレクトのように、git を実行せずにメインのチェックアウトへ書き込むコマンドは拒否されません。

• 対話型の worktree セッションを終了すると、変更済みまたは未追跡のファイル、サブモジュール内の未コミットの作業、新しいコミットなど、削除で失われる作業が無いかを確認します。
• 作業が無い場合、名前の無いセッションでは worktree とブランチを自動で削除し、名前付きのセッションでは先に確認を求めます。
• -p による非対話の実行には終了時の確認が無いため、その worktree は Claude が片付けません。
• サブエージェントやバックグラウンドセッション用に Claude が作った worktree は、cleanupPeriodDays 設定より古くなると、定期的な処理で削除されます。
• Claude が管理する worktree は、エージェント終了時にロック解除された状態で残るため、git worktree remove / prune で削除できます。
• git worktree remove が失敗しても rm -rf には切り替えないため、gitignore 対象のファイルや作業中のファイルは消えません。

• 分岐元の選択: worktree.baseRef 設定 (fresh | head) で、--worktree、EnterWorktree、エージェント分離用の worktree が origin/<default> から分岐するか、ローカルの HEAD から分岐するかを選べます。既定値は fresh で、未プッシュのコミットを新しい worktree に残すには worktree.baseRef: "head" を設定します。ブランチ名は指定できません。
• gitignore 対象ファイルのコピー: プロジェクトのルートに .worktreeinclude ファイルを置くと、.env のような未追跡のファイルを新しい worktree に自動でコピーします。書式は .gitignore と同じで、パターンに一致し、かつ gitignore 対象のファイルだけがコピーされます。
• バックグラウンドセッションの分離を外す: worktree.bgIsolation: "none" を設定すると、worktree が実用的でないリポジトリで、バックグラウンドセッションが EnterWorktree を使わずに作業コピーを直接編集します。
• 作成処理の置き換え: WorktreeCreate hook で既定の git worktree の処理を丸ごと置き換えられ、.claude/worktrees/ 以外の場所にも作成できます。SVN、Perforce、Mercurial などでは、WorktreeCreate と WorktreeRemove の hook で作成と後片付けの処理を用意します。hook を使う場合、--worktree では .worktreeinclude が処理されないため、ローカルの設定ファイルは hook のスクリプト内でコピーします。

ターミナルから --worktree フラグを付けて Claude Code を起動するのが基本の流れです。

1. --worktree または -w に名前を付けて起動します (例: claude --worktree feature-auth)。分離された worktree が作られ、その中で Claude が起動します。名前を省略すると、bright-running-fox のような名前が自動で付きます。
2. 別のターミナルで、異なる名前を付けて同じコマンドを実行すると、2 つ目の分離されたセッションを始められます。
3. 対話セッションを終了するとき、worktree に作業が残っていれば、残すか削除するかを選びます。後で戻るときは、終了時に表示される claude --worktree <name> --resume コマンドを実行します。