EnterWorktree / ExitWorktree（エンターワークツリー・エグジットワークツリー）

メインブランチを汚さずに、別ブランチで実験的な実装を Claude に並列でやらせたい人向け

EnterWorktree と ExitWorktree は、Claude Code がセッション中に裏で git worktree を切ったり戻ったりするための、ペアで動く内蔵ツールです。worktree というのは、同じ git プロジェクトを別フォルダ・別ブランチとして同時に開く仕組みのこと。私が普段やる「ログイン画面を作ってる途中で、別ブランチでログアウト処理のバグも触りたい」みたいな並行作業を、メインのブランチを汚さずに進めるための仕組みになっています。

起動時の --worktree 指定と混同しがちですが、フェーズが違います。--worktree は Claude を起動する時点で隔離した作業フォルダに入って始める指定で、EnterWorktree はすでに会話中の Claude に「ここからは別の作業ツリーで動いて」と頼んだ時に Claude が裏で叩く方のツール、という分担です。

噛み砕くと

同じプロジェクトのフォルダを「コピーじゃない別フォルダ」として丸ごともう1個用意する、と思ってください。中身のファイルは別、ブランチも別。でも履歴は共通。机の上にプロジェクトの作業セットを2セット並べて、片方で機能Aを書きながら、もう片方で機能Bを直す、みたいなイメージです。EnterWorktree で隣の机に移動、ExitWorktree で元の机に戻る、という対の操作になります。

気をつけたいのは、これは Claude が勝手に決めて発火させるツールであって、私たちが直接タイプして呼ぶものではないことです。「worktree を切って並行で進めて」と頼んだら、Claude が EnterWorktree を内部で実行して、新しい作業ツリーに移ってくれる、という流れになります。

大事な前提：subagent からは呼べない

これが一番引っかかりやすい所です。公式の tools-reference には verbatim で「Not available to subagents」と書いてある。つまり、Claude が Agent ツールで分身を呼び出して何か作業させても、その分身は自分の判断で worktree に入ったり出たりできない、という制約があります。

分身を別ツリーで動かしたい場合は別の仕組みを使う必要があって、公式は「サブエージェントの定義に isolation: worktree を書くと、Claude Code 側が自動で一時 worktree を切って分身を入れてくれる」という別ルートを案内しています。EnterWorktree をメインの Claude が叩いて、その中で分身を起動するやり方も可能です。

「メイン側でログイン画面、別ツリーでログアウト処理」を例に、実際の手順を見る

架空のWebアプリで、メインセッションでログイン画面の実装を進めている最中に、別件で「ログアウト周りのバグも先に潰しておきたい」となった、という設定で見ていきます。

ステップ1: メインセッションは普通に走らせておく

ターミナルAで普通に起動して、ログイン画面のコンポーネントを書いてもらっている状態だとします。

$ cd ~/projects/my-webapp
$ claude
> ログイン画面のコンポーネントを src/auth/Login.tsx に作って

この時点で Claude は main ブランチで作業しているはずです。ここはまだ何も特別なことはしていません。

ステップ2: 別件をやりたくなったので、Claude に worktree を切るよう頼む

同じ会話の中で、こう投げます。

> ちょっと別件で、ログアウト周りのバグを先に見たい。
  worktree を切って、そっちで作業して

すると Claude は内部で EnterWorktree を発火します。既定では .claude/worktrees/<名前>/ の下に新しい作業フォルダを作って、worktree-<名前> という新ブランチを切って、そこに移動します。元になるブランチは origin/HEAD なので、リモートの既定ブランチの最新状態から始まる、というのが既定動作です。

ステップ3: ここで初心者がやりがちな勘違い

「あれ、さっきまで書いてたログイン画面のファイルは？」と一瞬焦るやつです。これは消えていません。元の作業フォルダは別フォルダとしてそのまま残っています。今いる worktree のフォルダには、リモートの最新状態に乗った別ブランチのファイルが入っているだけ、という状態です。

git で除外しているファイル（.env など）は新しい worktree にはコピーされません。必要なら .worktreeinclude ファイルをプロジェクトの一番上に置いておくと、除外設定されているファイルのうちパターンに一致するものを自動でコピーしてくれます。

ステップ4: 別ツリーでバグ修正を進める

そのまま Claude にバグ修正を指示します。

> src/auth/Logout.tsx でセッション破棄の順番が逆になってる。直して

編集も保存区切りも全部この新ブランチに乗ります。メイン側の作業フォルダには1ミリも触れません。

ステップ5: 元の作業に戻る

修正が終わったら、こう頼みます。

> ログアウトの修正は終わったから、元のログイン画面の作業に戻して

Claude は内部で ExitWorktree を発火して、元のフォルダに戻ります。ここで後片付けの挙動が3パターンに分かれる、というのが重要です。

ステップ6: 後片付けの3パターン

公式は cleanup の挙動を verbatim で3つに分けて書いています。

• 未保存の変更も新規の保存区切りも何もない場合: その worktree とブランチは自動で削除される。ただしセッションに名前が付いている時は、削除せず保持するかを聞かれる
• 変更・未追跡ファイル・新規の保存区切りのどれかが残っている場合: 「保持するか削除するか」を聞かれる。保持を選ぶとフォルダもブランチも残るので、後で戻ってこられる。削除を選ぶと変更ごと全部消える
• 非対話実行: -p を付けて一発実行する形だと終了プロンプトが出ないので自動削除されない。git worktree remove で手動消去する必要がある

3つ目が地味な落とし穴です。スクリプトで claude --worktree foo -p "やっといて" みたいに回している人は、worktree がどんどん溜まっていきます。

つまり EnterWorktree / ExitWorktree は何をしてくれるのか

• やってくれる: 同じ git プロジェクトの別ブランチで作業するための隔離フォルダを自動で作って、そこに移動させてくれる。終わったら元のフォルダに戻してくれる
• やってくれる: すでに同じプロジェクト内に worktree フォルダがある場合は、新しく作らずに path を渡すだけでそちらに切り替える（公式: Pass a path to switch into an existing worktree of the current repository instead of creating a new one）
• やってくれる: PR 番号を #1234 の形か GitHub の PR URL で渡せば、その PR の pull/<番号>/head を fetch してきて、.claude/worktrees/pr-<番号> として開いてくれる
• やってくれない: 分身（subagent）から自分で呼ぶこと。公式が「Not available to subagents」と明記
• やってくれない: 任意の git ref からの分岐。worktree.baseRef 設定で受け付けるのは "fresh" か "head" の2択だけ
• 意味が薄い場面: 単一機能の単純な変更だけで完結する作業。むしろセットアップ分の手間が邪魔になる

使いどころ3シナリオ（具体題材で再現）

シナリオ1: SaaSの料金プラン変更画面を作ってる最中、サポートチームから「決済ログのバグ」を急ぎで頼まれた

料金プラン画面側で SubscriptionPlan.tsx を半分書き終わってる状態で、急ぎのバグ修正を別途やりたい。保存区切りも残しておきたいけど、料金プラン側のブランチには混ぜたくない。こういう時に「EnterWorktree で別ツリー切って、決済ログのバグだけ別ブランチで保存→PR、終わったら ExitWorktree で戻る」が綺麗にハマります。料金プランの作業ファイルは1秒も触られません。

シナリオ2: 外部の OSS で他人が出してる PR を、手元で動かして検証したい

GitHub の PR #4521 を「実際にビルドして動かして気になる所を見たい」みたいな時、EnterWorktree に PR 番号を渡すやり方が使えます。.claude/worktrees/pr-4521 として fetch されて、そこに切り替わる。検証が終わったら ExitWorktree。元のメイン作業に何の影響もありません。普段ローカルで PR をチェックアウトすると手元のブランチ状態が散らかりがちな問題が、この方式だと出にくいです。

シナリオ3: 「3つの実装案を並行で試して、後で比較したい」みたいな実験

例えば「認証フローを Cookie 方式 / セッショントークン方式 / OAuth委任方式 の3案で書かせて見比べたい」というケース。起動時の --worktree 指定で3つの作業ツリーを並べて、それぞれ別ターミナルで Claude を走らせて、別々の方向に育てる。EnterWorktree は「会話の途中で1案目から2案目に頭を切り替えたい時」に Claude に投げる発火、という補助になります。比較が終わったら、要らない方は ExitWorktree で削除を選ぶか、保持して残しておくかをその場で決められます。

初心者が踏みやすい落とし穴

• subagent から呼べない制約を知らずに「分身に worktree 切らせて並行作業」を期待する。これは無理。分身に隔離環境を持たせたい場合は、サブエージェント定義に isolation: worktree を書く方式を使う
• 新しいフォルダで初めて --worktree を使うと、いきなりエラーで弾かれる。先に claude だけを1回そのフォルダで叩いて、workspace trust のダイアログを通しておく必要がある。-p 付きでもこの制約は同じ
• -p 付き一発実行で worktree を放置しがち。終了プロンプトが出ないので自動削除されない。CI などで自動運用する場合は、別途 git worktree remove を回す仕組みを噛ませる
• PR 指定時に # マークを忘れる。claude --worktree 1234 だと普通の名前として解釈されて、worktree-1234 ブランチが新規で作られるだけ。PR を fetch したいなら "#1234" か PR URL を渡す
• worktree.baseRef に任意の git ref を入れようとする。受け付けるのは "fresh" か "head" の2択のみ。develop ブランチから切りたい、みたいな指定はできない。任意 ref から切りたいなら、手動で git worktree add を直接使うか、WorktreeCreate フックでロジック差し替え
• SVN や Perforce で .worktreeinclude が効くと思い込む。非 git のバージョン管理は WorktreeCreate/WorktreeRemove フックで対応する設計で、フック側が既定の git 動作を置き換えるので .worktreeinclude は処理されない。手元の設定ファイルをコピーしたいなら、フックスクリプトの中で自分でやる
• .claude/worktrees/ を .gitignore に入れ忘れる。メイン側のチェックアウトから見ると worktree のファイル群が未追跡ファイルとして全部見えてしまう。公式 Tip でもこれを入れろと書かれている
• 「worktree を切る」と「単に git checkout で別ブランチに切り替える」を混同する。後者は同じフォルダで状態が入れ替わるので、書きかけの作業が中断される。worktree は別フォルダなので作業を並行で残せる、というのが本質的な違い

書き方

（Claude が裏で発火させるツールなので、利用者が直接タイプすることはない）
# 会話の途中で頼む例
> このまま別件のバグを別ブランチで見たいから、worktree を切って作業して

# 起動時から隔離したい場合は --worktree 指定
claude --worktree feature-auth

# PR を fetch して worktree で開きたい場合
claude --worktree "#1234"

やってみるとこうなる

入力

> ログアウト周りのバグを先に潰したい。worktree を切って、そっちで作業して

出力例

Claudeが内部でEnterWorktreeを発火し、.claude/worktrees/<名前>/ の下に新しい作業フォルダを作成、worktree-<名前> という新ブランチを切って、そこに移動する。元になるブランチはorigin/HEAD（リモートの既定ブランチ）。元の作業フォルダは別フォルダとしてそのまま残る。修正が終わって「戻して」と頼むとExitWorktreeが発火し、元のフォルダに戻る。変更があれば「保持するか削除するか」をその場で聞かれる

関連項目

• --worktree（ワークツリー）
• Agent（エージェント）
• WorktreeCreate / WorktreeRemove（ワークツリークリエイト・ワークツリーリムーブ）
• SessionEnd（セッションエンド）
• /branch（ブランチ）

公式ドキュメント

https://code.claude.com/docs/en/worktrees