Claude Codeのworktree使い方｜並列作業を分ける手順

Claude Codeのworktreeとは、同じリポジトリを別の作業ディレクトリとブランチで並べて開き、セッションごとにファイルを分けて編集できる仕組みです。結論から言うと、複数のセッションを同時に動かして編集がぶつかるのを避けたいなら、claude --worktree（短縮形は-w）に名前を付けて起動するだけで、専用の作業ディレクトリと新しいブランチが用意されます。公式ドキュメントは、worktreeを「独自のファイルとブランチを持ち、リポジトリの履歴とリモートはメインのチェックアウトと共有する別の作業ディレクトリ」と説明しています（Run parallel sessions with worktrees）。

最小の起動コマンドは次の一行です。名前は自由に決められます。

claude --worktree feature-auth

実務で困りやすいのは、ひとつのセッションで機能追加を進めている最中に別の不具合修正を頼みたくなる場面です。同じフォルダで二つ目のセッションを開くと、互いの変更が混ざってしまいます。この記事では、仮の例として「認証まわりの機能追加」と「ログイン画面の不具合修正」を同時に進めるケースを想定し、worktreeの起動・環境の整え方・分岐元の選び方・終了時の片付け・サブエージェントとの併用・つまずきやすい点を、公式ドキュメントの記述だけを根拠に整理します。各段落には根拠となる公式ページのリンクを置きました。Claude Code自体の基本から知りたい方は、先にClaude Codeの基本的な使い方を読んでおくと用語がつながりやすくなります。

worktreeとは何か｜並列セッションでファイルを分ける仕組み

git worktreeは、同じリポジトリの履歴とリモートを共有しながら、別のフォルダと別のブランチで作業できるようにするgitの機能です。Claude Codeはこれをセッションの隔離に使い、あるセッションの編集が別のセッションのファイルに触れないようにします。

公式は、各セッションを専用のworktreeで動かせば一つのセッションの編集が他のセッションのファイルに影響せず、片方で機能を作りながらもう片方で不具合を直せると説明しています。元になるgitの仕組みはGit worktreeのドキュメントにまとまっており、Claude Codeの側の説明は公式のworktreesページにあります。worktreeにはgitリポジトリが必要で、git以外のバージョン管理を使う場合はフックで作成処理を置き換える形になります。

worktreeは並列で動かす方法のうちの一つにすぎません。公式は、worktreeが担うのはファイル編集の隔離であり、一つのセッションの中で仕事を分けるのがサブエージェント、セッション同士で調査結果を渡すのがセッション間メッセージだと整理しています（Run parallel sessions with worktrees）。サブエージェントの基本はサブエージェントの設定と使いどころで扱っているので、役割の違いを比べたいときに参照してください。

並列の方法	分けるもの	向いている場面
worktree	ファイル編集（作業ディレクトリとブランチ）	機能追加と不具合修正を別々のセッションで同時に進めたいとき
サブエージェント	一つのセッション内の仕事	調査や機械的な修正を切り出して本体の文脈を軽く保ちたいとき
セッション間メッセージ	セッション同士の情報	worktreeごとのセッションが調べた内容を互いに渡したいとき

上の表は公式が示す役割分担を、この記事の読者向けに三つの軸で並べ直したものです。どれか一つを選ぶというより、worktreeで編集を分けたうえで、各セッションの中でサブエージェントを使う、といった組み合わせ方が現実的です。

基本の起動手順｜–worktreeで隔離セッションを始める

起動はclaude --worktree <名前>（または-w）です。既定では、リポジトリのルート直下の.claude/worktrees/<名前>/に作業ディレクトリが作られ、worktree-<名前>という新しいブランチでセッションが始まります。

公式のコマンド例は、名前にfeature-authを渡す形です。別のターミナルで違う名前を渡して同じコマンドを実行すれば、二つ目の隔離セッションが始まります。名前を省けばClaudeがbright-running-foxのような名前を自動で付けます（Start Claude in a worktree）。先ほどの仮の例なら、片方のターミナルで次を実行し、もう片方で名前違いを実行する流れです。

claude --worktree feature-auth
claude --worktree bugfix-login

コマンドラインのフラグとしての定義は、公式のCLIリファレンスにも載っています。--worktreeと-wは「<repo>/.claude/worktrees/<name>に隔離したgit worktreeを作ってClaudeを始める」フラグで、名前を省くと生成されます。同じ表に、--worktreeが必須の--tmuxフラグも載っており、claude -w feature-auth --tmuxの形でworktree用のtmuxセッションを作れると書かれています（CLI reference）。

対話セッションの途中からworktreeに入ることもできます。公式によると、セッション中にClaudeへ「worktreeで作業して」と頼むと、EnterWorktreeツールでworktreeが作られます。すでにworktreeの中にいる場合は、.claude/worktrees/配下の別のworktreeへ、対象のパスを指定して直接切り替えることもでき、前のworktreeはそのままディスクに残ります（Ask Claude to create a worktree）。デスクトップアプリでは、セッションを始めるときにworktreeのオプションを選ぶと専用のworktreeが割り当てられます。

作成先・ブランチ名・事前条件｜初回に確認しておくこと

初回は、対象ディレクトリでワークスペースの信頼ダイアログを承認済みであることが条件です。あわせて、.claude/worktrees/を.gitignoreへ追加しておくと、worktreeの中身がメインのチェックアウトで未追跡ファイルとして見えなくなります。

公式は、対話実行ではワークスペースの信頼が必要だと書いています。そのディレクトリでClaudeを一度も動かしていなければ、先にclaudeを一度だけ実行して信頼ダイアログを承認しておかないと、--worktreeはエラーで終了します。一方、-pを付けた非対話実行は信頼確認を省くため、claude -p --worktreeはそのまま進みます（Start Claude in a worktree）。-pの使い方そのものはヘッドレスモードの解説にまとめています。

項目	既定の挙動	補足
作成先	リポジトリのルート直下の.claude/worktrees/<名前>/	フックで作成処理を置き換えると別の場所にもできる
ブランチ名	worktree-<名前>	新しいブランチとして作られる
名前を省いたとき	Claudeが名前を生成する	bright-running-foxのような形
初回の条件	信頼ダイアログの承認	未承認だと--worktreeはエラーで終了する
非対話実行	信頼チェックを省く	claude -p --worktreeはそのまま進む

表の内容はすべて先ほどの公式ページの記述に沿っています。特にブランチ名は、名前に指定した文字列の前にworktree-が付く点を覚えておくと、あとでgit branchの一覧を見たときに由来が分かります。

もう一点、公式は.claude/worktrees/を.gitignoreに足すことを推奨しています。worktreeの中のファイルがメインのチェックアウトから未追跡として見えて、コミットの対象に混ざるのを避ける目的です。プロジェクトの.gitignoreに次の一行を追加しておけば足ります。

.claude/worktrees/

新しいworktreeの環境を整える｜依存関係と.envの扱い

worktreeは新しいチェックアウトなので、依存関係のインストールなど開発環境の初期化は各worktreeで改めて必要です。.envのようなgitignore対象のファイルは、.worktreeincludeファイルを置くと新しいworktreeへ自動でコピーされます。

公式は、worktreeを新しいチェックアウトとして扱い、Claudeに依存関係のインストールを頼むか、.claude/worktrees/配下の作業ディレクトリでプロジェクトの初期化手順を自分で実行するよう案内しています（Set up the worktree environment）。メインのリポジトリでは動いていた環境変数や設定ファイルが、新しいworktreeでは見当たらない、というのが最初に出やすいつまずきです。

その対策が.worktreeincludeです。プロジェクトのルートに置くと、Claudeがworktreeを作るときに、未追跡のファイルを自動でコピーします。書式は.gitignoreと同じで、パターンに一致し、かつgitignoreの対象でもあるファイルだけがコピーされるため、追跡中のファイルが重複することはありません。公式の例は次のとおりです（Copy gitignored files into worktrees）。

.env
.env.local
config/secrets.json

この仕組みは、--worktreeで作るworktree、サブエージェント用のworktree、デスクトップアプリの並列セッションなど、Claude Codeがgitで作るすべてのworktreeに適用されます。フックで作成処理を置き換えた場合は、コピー処理をフックのスクリプトの中に書く必要があります。**/で始まるパターンの細かい挙動には条件があり、公式は、丸ごとgitignoreされたディレクトリの中にあるファイルを**/で指すときの例外を解説しています。該当しそうなときは上のリンク先で確認してください。

大きなディレクトリを複製したくない場合は、設定ファイルのキーも使えます。公式の設定リファレンスでは、worktree.symlinkDirectoriesにリポジトリのルートからの相対パスを並べると、そのディレクトリがメインのリポジトリから各worktreeへシンボリックリンクされ、ディスク上に重複しないと説明されています。既定では何もリンクしません。公式の例は、node_modulesと.cacheをリンクする次の設定です（Settings reference）。

{
  "worktree": {
    "symlinkDirectories": ["node_modules", ".cache"]
  }
}

同じ設定リファレンスには、大きなモノレポ向けのworktree.sparsePathsもあります。指定したディレクトリとルート直下のファイルだけをgitのスパースチェックアウトで各worktreeに書き出す設定で、既定では全体をチェックアウトします。settings.jsonにキーを書く流れは、権限設定の解説でも同じ形で登場するので、あわせて見ると位置づけが分かりやすくなります。

分岐元を選ぶ｜worktree.baseRefとプルリクエスト指定

新しいworktreeは、既定ではリモートの既定ブランチから分岐します。手元の未プッシュのコミットを引き継ぎたいときは、設定でworktree.baseRefを"head"にします。特定のプルリクエストから始めたいときは、--worktreeに番号かURLを渡します。

公式の設定リファレンスによると、worktree.baseRefの値は二つです。"fresh"が既定で、origin/<既定ブランチ>から分岐するので、リモートと同じ状態のきれいなツリーで始まります。"head"は現在のローカルのHEADから分岐し、未プッシュのコミットや機能ブランチの状態がworktreeに含まれます。worktreeの内側では、"head"はメインのチェックアウトではなくそのworktreeのHEADを指します（Settings reference）。設定例は次のとおりです。

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

注意点として、worktree.baseRefにブランチ名は指定できません。公式は、既存の特定のブランチから始めたいときはgitで直接worktreeを作るよう案内しています。また、リモートが設定されていない場合やorigin/HEADが取得できない場合は、現在のローカルのHEADへフォールバックすると書かれています（Choose the base branch）。

プルリクエストやマージリクエストの内容を確かめたいときは、--worktreeに#付きの番号、GitHubのプルリクエストのURL、GitLabのマージリクエストのURLのいずれかを渡します。Claude Codeはoriginからその変更のheadコミットを取得し、.claude/worktrees/pr-<番号>にworktreeを作ります。シェルが#をコメントの開始と解釈しないよう、引数は引用符で囲みます（Branch from a pull request）。

claude --worktree "#1234"

取得先はoriginのホストで決まります。github.comならpull/<番号>/head、gitlab.comならmerge-requests/<番号>/headを取得し、GitHub Enterpriseやセルフマネージドのような他のホストでは、まずpull/<番号>/headを試してからmerge-requests/<番号>/headを試します。URLから読み取るのは番号だけで、取得は常にリポジトリのoriginに対して行われる点も公式が明記しています。

終了時のクリーンアップ｜worktreeが消える条件と残る条件

対話セッションを終了するとき、Claudeはworktreeの中に削除で失われる作業がないかを調べます。何も変更がなければ自動で消え、作業が残っていれば保持するか削除するかを尋ね、状態が確認できないときも自動では消さずに尋ねます。

公式の記述では、確認の対象は、変更済みまたは未追跡のファイル、チェックアウト済みのサブモジュール内の未コミットの作業、そして新しいコミットです。この規則はgitでClaudeが作ったworktreeに適用されます。結果は次の表のとおりです（Clean up worktrees）。

worktreeの状態	終了時の動作
変更がない（名前を付けていないセッション）	worktreeとブランチが自動で削除される
変更がない（名前を付けたセッション）	あとで使えるよう、保持するかどうかを先に尋ねる
作業が残っている	保持か削除かを尋ねる。保持するとディレクトリとブランチが残り、削除すると作業ごと消える
状態を検証できない	自動では削除せず、確認できなかった内容を示して尋ねる

保持を選んだ場合、あとで戻るには終了時にClaude Codeが表示するclaude --worktree <名前> --resumeのコマンドを使います。削除を選ぶとworktreeのディレクトリとブランチが、その中の作業ごと消えるので、コミットやプッシュが済んでいない変更が残っていないかを選ぶ前に見直してください。名前を付けたセッションの扱いは、セッション管理の解説にある名前付けと合わせて読むと理解しやすくなります。

非対話の-p実行には終了時の確認がないため、Claudeはそのworktreeを片付けません。作成時に取られたロックも、あとのセッションによる古いロックの掃除が解放するまで残ります。手動で消すならgit worktree removeを使い、ロックで拒否された場合は先にgit worktree unlockを実行します（Clean up worktrees）。

同じ名前の再利用とセッションの再開｜戻ったときに何が起きるか

すでにディレクトリがある名前を--worktreeに渡すと、新規作成ではなく既存のworktreeが開かれます。worktreeの中で終わったセッションを再開すると、Claude Codeはそのセッションを同じworktreeへ戻します。

名前の再利用について、公式は細かい条件を書いています。既定の"fresh"の基準では、未コミットの変更も未追跡ファイルもなく、Claude Codeが作ったブランチの上にいて、独自のコミットがないか、プルリクエストがマージされてリモートのブランチが削除されている場合に限り、再度開いたworktreeは古い先端ではなく既定ブランチへリセットされます。それ以外の場合、状態を確認できない場合、worktree.baseRefが"head"の場合、名前がプルリクエストやマージリクエストの参照の場合は、古い先端のまま開き直されます（Reuse a worktree name）。巻き戻しが起きるのは、公式の条件をすべて満たす場合に限られます。

セッションの再開については、公式が、worktreeを抜けないまま終了したセッションを再開すると同じworktreeへ戻ると説明しています。これは対話の再開に加え、非対話モードの-pと組み合わせた--continueや--resume、Agent SDKにも当てはまります。戻った先では、ClaudeはExitWorktreeツールでそのworktreeから抜けることもできます（Resume a worktree session）。

戻る前の確認もあります。Claude Codeは、そのworktreeがメインとは別のチェックアウトのままであることを検証し、検証に通らないworktreeへの再入場を断ります。再開の起点にも注意が必要で、公式は、--resumeをメインのチェックアウトやリポジトリ内の別のディレクトリから実行するよう案内しています。Claude Codeがgitで.claude/worktrees/配下に作ったworktreeは、その中から起動しても再入場されます。一方、自分でgit worktree addして作ったworktreeの配下のサブディレクトリから起動した場合などは再入場されないことがあり、その場合はメインのチェックアウトから起動します。また、--fork-sessionで分岐したセッションは、Claudeを起動したディレクトリで始まり、元のセッションのworktreeには触れません。worktreeのディレクトリがすでに消えている場合は、起動したディレクトリで再開され、その旨が表示されます。

セッション選択の画面にも関連する操作があります。公式のセッション管理ページによると、選択画面の既定の一覧には現在のworktreeのセッションが並び、Ctrl+Wでリポジトリのすべてのworktreeのセッションへ広げられます。--resumeにセッションIDを渡した場合も、現在のプロジェクトのディレクトリとそのgit worktreeをまず探し、その後でマシン上の他のプロジェクトを探します（Manage sessions）。再開の基本は、別記事のセッションの再開方法で手順を整理しています。

分離のしくみ｜4つのチェックで本体のチェックアウトを守る

worktreeで隔離されたセッションでは、Claude Codeがメインのチェックアウトに触れるツール呼び出しを止めます。チェックは四種類で、ファイル編集、コマンドの作業ディレクトリ、gitのリダイレクト、コマンドの形を対象にします。

公式は、この隔離が--worktreeで始めた場合、EnterWorktreeでClaudeが入った場合、worktreeセッションを再開した場合のどれでも同じように働くと説明しています。さらに、隔離されたセッションから生まれたすべてのサブエージェントにも同じ強制が及びます（How Claude Code enforces isolation）。四つのチェックの中身は次のとおりです。

チェック	止める対象
ファイル編集	メインのチェックアウト内のパスを対象にしたEdit、Write、NotebookEdit
コマンドの作業ディレクトリ	作業ディレクトリがメインのチェックアウトになる、または検証できずにその外にあると言えないBash、PowerShell、Monitorのコマンド
gitのリダイレクト	git -C、--git-dir、GIT_DIRやGIT_WORK_TREEの変数、メインのチェックアウトへのcdによって、gitをメインのチェックアウトへ向けるコマンド
コマンドの形	コマンド名が実行時に計算される、構文を解析できないなど、実行するgitがworktreeの中に留まると文面から確認できないコマンド

拒否されたとき、Claudeはworktreeの名前と進め方を示すツールエラーとして受け取ります。コマンドの形のチェックでは、Claude Codeが拒否したコマンドの書き直し方、たとえば単純な別々のコマンドへ分けることをClaudeに伝えます。公式は、このコマンドの形のチェックは無効にできないとも明記しています。チェックはClaude Codeを起動したリポジトリに適用され、リンクされたworktreeの元になっているメインのチェックアウトも対象です。PowerShellのコマンドには作業ディレクトリのチェックだけが適用されます。

フックを使っている場合は挙動の違いに注意が必要です。公式によると、Claudeがworktreeに入ったあとも、フックの${CLAUDE_PROJECT_DIR}はセッションを始めたプロジェクトのルートを指したままです。worktreeのパスは、フックへ渡される入力JSONのcwdフィールドで渡され、Claudeがcdを実行するとそれに追随します。worktreeのパスが必要なフックはcwdを読むようにします（Ask Claude to create a worktree）。フックの書き方自体はフックの設定とイベント一覧で整理しています。

サブエージェントをworktreeで隔離する｜isolation: worktreeの使い方

サブエージェントを専用のworktreeで動かせば、並列の編集が衝突しません。Claudeに「use worktrees for your agents」と頼むか、カスタムサブエージェントのフロントマターにisolation: worktreeを書いて恒久的にします。

公式の例は、.claude/agents/に置くサブエージェントのファイルです。次の定義のサブエージェントは、常に自分専用のworktreeで動きます（Isolate subagents with worktrees）。

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---

Apply the requested refactor across every affected file, then run the tests
and report the results.

それぞれのサブエージェントには一時的なworktreeが与えられ、変更なしで終わればClaude Codeが自動で削除します。変更があるworktreeは、あとで説明する定期的な掃除が、作業を失わずに消せるようになるまでディスクに残ります。サブエージェントのworktreeの分岐元は--worktreeと同じ基準で、worktree.baseRefを"head"にしない限り、リポジトリの既定ブランチから分岐します。サブエージェント側のフロントマターの一覧にもisolationがあり、worktreeを設定すると一時的なgit worktreeで動き、親セッションのHEADではなく既定ブランチから分岐する、と書かれています（Create custom subagents）。

残ったworktreeの掃除については、公式が次のように説明しています。Claude Codeは、サブエージェントやバックグラウンドセッション用に作ったworktreeのうち、設定cleanupPeriodDaysより古いものを定期的に掃除します。ただし、作業が残っている場合、チェックアウト済みサブモジュールに変更がある場合、--worktreeセッションで、まだバックグラウンドへ移していないものである場合、自分でgit worktree addを実行して作ったものである場合は、掃除の対象から外れます。エージェントが動いている間は、同時の掃除で消されないようgit worktree lockが取られ、終了すると解放されます。掃除が残したworktreeを消すにはgit worktree removeを使い、未コミットの変更や未追跡ファイルがあれば--forceを加えます。

サブエージェント全般の使いどころはサブエージェントの記事にまとめています。worktreeで隔離するかどうかは、そのサブエージェントが複数ファイルを書き換えるか、読むだけかで判断するのが分かりやすい基準です。読み取り専用の調査なら、隔離せずに並べても編集は衝突しません。

worktreeがメインと共有するもの｜gitと設定の境界

worktreeが分けるのはファイルとブランチだけで、リポジトリの.gitディレクトリ、プロジェクトスコープのプラグイン、Bashコマンドの許可の記録などはメインのチェックアウトと共有されます。

公式は、共有されるものを四つ挙げています。一つ目はリポジトリの.gitディレクトリで、worktreeの中のgitコマンドは共有の.gitに書き込みます。サンドボックスもこの書き込みを許可するため、サンドボックスが有効でもworktreeの中でgit commitが動きます。二つ目は、メインのチェックアウトからプロジェクトスコープで入れたプラグインで、同じリポジトリのworktreeでも読み込まれるため、worktreeごとの入れ直しは要りません。プラグインの全体像はプラグインの使い方で扱っています。

三つ目は許可の記録です。worktreeのセッションでBashコマンドに対して「Yes, and don’t ask again」を選ぶと、そのルールはメインのチェックアウトの.claude/settings.local.jsonへ保存されます。そのため、メインのチェックアウトと、同じリポジトリの他のすべてのworktreeにも効き、worktreeを削除したあとも残ります。ただし、Windowsなど、Claude Codeがリポジトリのルートを使わない場合は、ルールがそのworktreeに留まります（What worktrees share with the main checkout）。権限ルールの考え方は権限設定の記事で詳しく扱っています。

共有されるもの	worktreeでの現れ方
リポジトリの.gitディレクトリ	worktree内のgitコマンドが共有の.gitへ書き込む。サンドボックス有効でもgit commitが動く
プロジェクトスコープのプラグイン	メインで入れたプラグインが同じリポジトリのworktreeでも読み込まれる
Bashコマンドの許可の記録	メインの.claude/settings.local.jsonに保存され、他のworktreeにも効き、worktreeの削除後も残る
未追跡のスキル・エージェント・コマンド	worktreeに.claude/skillsがない場合、メインのプロジェクトスキルが読み込まれる

四つ目は、未追跡のスキル、エージェント、コマンドです。たとえば.claude/skillsがgitignoreされていてworktreeのチェックアウトに存在しない場合、Claude Codeはメインのチェックアウトのプロジェクトスキルをworktreeのセッションでも読み込みます。worktree自身に.claude/skillsディレクトリがあれば、そちらだけが読み込まれます。同じ読み通しは.claude/agentsと.claude/commandsにも及びます。スキルの仕組みはスキルの設定と呼び出し方を参照してください。これらはすべて、--worktreeで作った場合も、git worktree addで作った場合も、デスクトップアプリ経由の場合も同様だと公式は書いています。

gitで手動作成する方法と、git以外のバージョン管理

既存のブランチをそのまま使いたい、あるいはリポジトリの外に置きたいときは、gitで直接worktreeを作ってからそこでClaudeを起動します。git以外のバージョン管理では、WorktreeCreateとWorktreeRemoveのフックで作成と片付けを自前で書きます。

公式が示す手動の手順は、まず新しいブランチ付きでworktreeを作るコマンドです。続いて、既存のブランチから作る例では、fix-issue-456の部分を、リポジトリにすでにあるブランチ名へ置き換えます（Manage worktrees manually）。

git worktree add ../project-feature-a -b feature-a
git worktree add ../project-bugfix fix-issue-456

作ったあとは、そのディレクトリへ移動してClaudeを起動します。一覧の確認と削除には、次の二つのコマンドを使います。

cd ../project-feature-a
claude
git worktree list
git worktree remove ../project-feature-a

手動で作ったworktreeには、掃除の扱いに違いがあります。前の節で触れたとおり、自分でgit worktree addを実行して作ったworktreeは、定期的な掃除の対象になりません。また、Claude Codeは自分がgitで作ったworktreeのgitメタデータに印を書き込み、印のないworktreeは掃除で残します。手動のworktreeを片付けるのは自分の仕事になる、と覚えておくと後始末を忘れません。

git以外のバージョン管理、つまりSVN、Perforce、Mercurialなどでは、公式がWorktreeCreateとWorktreeRemoveのフックを設定して、独自の作成処理と片付け処理を用意するよう案内しています。フックが既定のgit動作を置き換えるため、--worktreeでは.worktreeincludeが処理されません。ローカルの設定ファイルのコピーは、フックのスクリプトの中で行います。公式の例は、標準入力のJSONからjqでworktreeの名前を読み取り、新しいSVNの作業コピーをチェックアウトして、そのディレクトリを出力するWorktreeCreateフックです（Non-git version control）。

{
  "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のフックを組み合わせることも勧めています。入力の形式や削除の例はフックのリファレンスにあります。WorktreeCreateのフックがあると、gitリポジトリの外でも/batchを実行できる点も、公式のページに書かれています。

つまずきやすい点と対処｜エラーメッセージ別の早見表

worktree関連のエラーは、メッセージの書き出しで原因を切り分けられます。よく出るのは、シンボリックリンクのパス、Git LFSのポインタファイル、再開時に元のworktreeへ戻れないケースです。

公式のトラブルシューティングには、worktreeの作成時、起動時の入場、再開時の復帰で出るエラーが整理されています。初めて遭遇しやすいものを表にまとめました。詳細な分岐は各リンク先にあります（Troubleshooting）。

症状	公式の説明と対処
.claude、.claude/worktrees、またはworktreeのディレクトリがシンボリックリンク	作成が拒否され、エラーにリンクのパスが示される。リンクを取り除いて再実行する
Git LFSのファイルがポインタファイルのまま	git lfs install --localで設定した場合に起きる。worktree内でgit lfs pullを実行して実体を取得する
Refusing to use <path> as an isolation worktree	ディレクトリのgit情報がメインのチェックアウトに解決されるなどの理由で、隔離worktreeとして採用されなかった。後続のメッセージに従う
Your worktree <path> no longer exists	再開時にworktreeのディレクトリが消えている。セッションは現在のディレクトリで、隔離なしで続く。対応は不要
Could not re-enter your worktree <path>	起動した場所からworktreeを確認できなかった。多くはworktreeの中から起動した場合。メッセージが示す修正に従う

Git LFSについては、公式が背景も説明しています。git lfs install --localはLFSのフィルターをリポジトリ自身の.git/configへ書き込みます。Claude Codeは、フィルタードライバーがシェルコマンドであり、リポジトリに書き込めるもの、つまりClaude自身を含む何かが仕込める可能性があるため、worktreeの作成時にリポジトリ自身のフィルタードライバーを使いません。グローバルなgit設定に書き込む通常のgit lfs installは影響を受けません（Git LFS files are pointer files in a worktree Claude Code created）。

再開まわりのエラーは、対話と非対話で出方が違います。対話の再開では、復帰できない場合に上の表のような通知が出てセッションが続きます。一方、-pによるヘッドレス実行やAgent SDKの再開では、worktreeがすでに消えている場合を除くすべての拒否で、標準エラーへのエラーとともに再開が止まります。さらに--output-format stream-jsonを使うと、error_during_executionというサブタイプのresultメッセージが標準出力にも届くので、アプリケーションは理由を受け取れます。startup_failure_reasonの値を見れば、エラー文を照合せずに分岐もできます（The session resumes outside its worktree）。使用量や実行コストが気になる場合は、使用量とコストの確認方法もあわせて参照してください。

よくある質問（FAQ）

Q1. worktreeを使うには何が必要ですか？

gitリポジトリです。公式は、worktreeにはgitリポジトリが必要で、他のバージョン管理ではフックで置き換えると案内しています。初回はそのディレクトリでClaudeを一度起動して、信頼ダイアログを承認しておいてください（公式ドキュメント）。

Q2. worktreeを作ると、メインのフォルダの内容とは何が違いますか？

公式の説明では、worktreeは独自のファイルとブランチを持つ別ディレクトリで、既定ではリモートの既定ブランチから分岐します。手元の未プッシュのコミットや機能ブランチの状態を含めたいときは、worktree.baseRefを"head"にします（設定リファレンス）。

Q3. .envが新しいworktreeにありません。どうすればよいですか？

プロジェクトのルートに.worktreeincludeを置き、コピーしたいファイル名を.gitignoreと同じ書式で並べます。gitignoreの対象でもあるファイルだけがコピーされます（公式の該当節）。

Q4. 手動で作ったworktreeは自動で削除されますか？

定期的な掃除の対象にはなりません。公式によると、自分でgit worktree addを実行して作ったものは、その後--worktree <名前>のセッションを動かしてバックグラウンドへ移しても、掃除されずに残ります。不要になったらgit worktree removeで消します。

Q5. 特定のブランチからworktreeを始められますか？

worktree.baseRefにブランチ名は指定できないと、公式が明記しています。既存のブランチから始めるなら、git worktree addでworktreeを作ってからそこでClaudeを起動します。プルリクエストやマージリクエストからなら、--worktreeに番号かURLを渡せます。

Q6. 削除したworktreeの中の作業は戻せますか？

終了時に「削除」を選ぶと、worktreeのディレクトリとブランチが作業ごと消えると公式は説明しています。消す前にコミットやプッシュが済んでいるかを確認し、迷うときは保持を選んでください。保持すれば、表示された--resume付きのコマンドで戻れます。

まとめ｜worktreeで並列セッションを安全に分ける

Claude Codeのworktreeは、claude --worktree <名前>の一行で、専用の作業ディレクトリと新しいブランチを持つ隔離セッションを始められる機能です。既定の作成先は.claude/worktrees/<名前>/、ブランチ名はworktree-<名前>で、.gitignoreへの追加と、初回の信頼ダイアログの承認を済ませておけば、すぐに並列作業に入れます。根拠はすべて公式のworktreesページと設定リファレンスの記述です。

実際に使い始めるときは、次の順で進めると迷いません。まず.gitignoreに.claude/worktrees/を足し、.envなどが必要なら.worktreeincludeを置きます。手元の未プッシュのコミットを引き継ぎたいときだけworktree.baseRefを"head"にし、終了時は保持か削除かの確認をよく読んで選びます。サブエージェントの編集が衝突しそうならisolation: worktreeを足します。設定の読み込み順やCLAUDE.mdとの関係はCLAUDE.mdの書き方、巻き戻しの手段はチェックポイントと/rewindの使い方が補ってくれます。

なお、機能や版ごとの挙動の違いは公式ページに版の注記として残っています。お使いの版で動きが違うと感じたら、まず公式の該当節を確認してください。AIツールの最新情報や活用のコツは、LINEで受け取れる特典もあわせてご覧ください。