Claude Code worktreeとは？使い方・設定・片付け方を解説

「Claude Codeに機能の追加を頼んでいる間に、別の不具合も直してもらいたい」「2つのClaudeに同じフォルダで作業させたら、ファイルが混ざってしまった」という場面は、使い込むほど増えてきます。

こうした場面で使うのがworktree（ワークツリー）です。同じプロジェクトを、別のフォルダ・別のブランチ（変更を分けて進めるための枝）としてもう1つ取り出し、そこでClaudeに作業させます。作業場所が分かれるので、並行して頼んでも、お互いの編集が混ざりません。Claude Codeでは、起動時に --worktree と名前を付けるだけで使えます。

この記事では、worktreeの仕組みと他の並列の仕組みとの違いから、始め方、終了時の片付け、設定、サブエージェントやデスクトップアプリでの使い方、うまく動かないときの対処までを順に解説します。内容は2026年10月時点の公式ドキュメントをもとにしています。Claude Codeは更新が頻繁なので、使う前に公式ドキュメントもあわせて確認してください。

worktreeとは

worktreeは、もともとバージョン管理の仕組み「Git」の機能です。公式ドキュメントでは、自分専用のファイルとブランチを持つ別の作業フォルダで、変更履歴とリモート（GitHubなどの保管先）は元のフォルダと共有するものと説明されています。

ふつうは、プロジェクトのフォルダが1つあり、そこで作業するのは1回に1つの仕事だけです。worktreeを使うと、同じプロジェクトを別のフォルダにもう1つ取り出せます。たとえば、1つ目では新機能を作り、2つ目では不具合の修正を進める、という分け方ができます。

Claude Codeは、並行して頼まれた仕事が同じファイルを触ると、お互いの変更を上書きしたり、作りかけの状態を読み込んだりしてしまいます。Claudeのセッションごとにworktreeを分けておけば、各セッションが自分専用のコピーを編集するので、こうした混線を防げます。

他の並列の仕組みとの違い

Claude Codeには、複数の仕事を同時に進める仕組みがいくつかあります。worktreeは、その中で「ファイルの編集を分ける」ことだけを担当する部品です。公式ドキュメントでも、worktreeは並列に動かす方法そのものではなく、それを支える道具として整理されています。

つまり、自分でターミナルを複数開いて、それぞれにClaudeを動かす使い方では、worktreeが主役になります。サブエージェントやエージェントビューを使う場合は、裏側でworktreeが使われます。

worktreeが向いている場面

なお、worktreeを使うにはGitが入っていて、プロジェクトがGitで管理されている必要があります。Git以外のバージョン管理を使っている場合は、後述するフックの設定が必要です。

worktreeの使い方

基本の使い方は、1つのコマンドです。--worktree（短く書く場合は-w）に名前を付けてClaude Codeを起動します。

claude --worktree feature-auth

これで、feature-authという名前のworktreeが作られ、その中でClaudeが起動します。別のターミナルで、別の名前を付けて同じコマンドを実行すれば、2つ目の独立したセッションが始まります。

最初の1回の手順

1. プロジェクトのフォルダに移動するGitで管理しているプロジェクトのフォルダを、ターミナルで開きます。そのプロジェクトで初めてClaude Codeを使う場合は、先にclaudeだけを一度起動して、フォルダを信頼するかの確認に答えておきます。確認が済んでいないと、--worktreeはエラーで終了します。
2. 名前を付けて起動するclaude --worktree 名前を実行します。名前は作業内容が分かるものにします（例：feature-auth、fix-login）。名前を省略すると、bright-running-foxのような名前が自動で付きます。
3. Claudeに作業を頼む通常のセッションと同じように依頼を書きます。ファイルの編集は、このworktreeの中だけで行われます。
4. 別の作業は、別のターミナルで始める2つ目のターミナルを開き、別の名前でclaude --worktreeを実行します。2つのセッションは互いのファイルに触れません。
5. 終了して、片付けを選ぶ作業が終わったらセッションを終了します。worktreeを残すか消すかは、次の章で説明する条件に応じて決まります。

作られる場所とブランチ名

Windowsでも考え方は同じで、プロジェクトの .claude\worktrees\ の下に作られます。

worktreeの中の準備

worktreeは新しいチェックアウトなので、元のフォルダにある依存ファイル（node_modulesなど）や、Gitに入れていない設定ファイル（.envなど）は入っていません。Claudeに「依存関係をインストールして」と頼むか、worktreeのフォルダでプロジェクトのセットアップ手順を自分で実行します。毎回コピーしたいファイルがある場合は、後述する.worktreeincludeに書いておけます。

会話の途中で「worktreeで作業して」と頼む

起動時に指定しなくても、セッションの途中でClaudeに「worktreeで作業して」と頼めば、ClaudeがEnterWorktreeというツールを使って作ってくれます。worktreeの中にいる間は、.claude/worktrees/の下にある別のworktreeへ切り替えることもでき、前のworktreeはそのまま残ります。

切り替え先が.claude/worktrees/の外にある場合は、Claude Codeが事前に承認を求めます。作業フォルダ・書き込み権限・CLAUDE.mdや設定が、その場所に移るためです。この確認は、権限ルールの設定や「今後は確認しない」を選んでも省略できません。

プルリクエストの内容から始める

レビューや修正のために、特定のプルリクエスト（変更の提案）の状態から始めたいときは、--worktreeに番号を渡します。#はシェルでコメントの開始と解釈されるので、引用符で囲みます。

claude --worktree "#1234"

GitHubのプルリクエストのURL、GitLabのマージリクエストのURLも指定できます。Claude Codeが、そのプルリクエストの最新の状態をoriginから取得し、.claude/worktrees/pr-1234のような名前でworktreeを作ります。GitLabのマージリクエストを使うにはClaude Code v2.1.233以降が必要です。取得の際にパスワードやパスフレーズの入力が必要になる場合は、取得が失敗してエラーで終了します。SSHの鍵はあらかじめssh-agentに読み込んでおいてください。

tmuxと一緒に使う

ターミナルの分割ツール「tmux」を使っている場合は、--tmuxを付けると、worktree用のtmuxセッションが作られます。--worktreeと一緒に指定する必要があります。

claude -w feature-auth --tmux

iTerm2が使える環境では、iTerm2のネイティブなペインが使われます。従来のtmuxを使いたい場合は--tmux=classicを指定します。

片付け・再開

worktreeは作りっぱなしにするとフォルダが増えていきます。Claude Codeは、セッションを終了するときに、worktreeの中に消すと失われる作業（変更したファイル、新しいファイル、新しいコミット）があるかを確認し、その結果に応じて動きます。

残したworktreeで作業を再開する

worktreeを残して終了すると、Claude Codeが再開用のコマンドを表示します。次のような形で、同じworktreeに戻れます。

claude --worktree feature-auth --resume

worktreeの中で終了した（片付けを選ばずに閉じた）セッションを再開した場合は、Claude Codeが自動でそのworktreeに戻します。元のプロジェクトのフォルダなど、worktreeの外から--resumeを実行する方法でも戻れます。一方、worktreeのフォルダ自体がすでに削除されている場合は、起動したフォルダでセッションが再開され、worktreeがなくなったことが表示されます。

同じ名前をもう一度使ったとき

すでにあるworktreeと同じ名前を指定すると、新しいworktreeは作られず、既存のものが開かれます。このとき、起点が既定の"fresh"の場合は、次の条件がすべて当てはまると、前回の続きではなくリポジトリの既定ブランチの状態にリセットされます。

• 未コミットの変更や未追跡のファイルがない
• Claude Codeが作ったブランチのままになっている
• 自分のコミットがない、または、プルリクエストがマージされてリモートのブランチが削除されている

それ以外の場合は、前回の最後の状態のまま開かれます。作業を続けたいときは、同じ名前で再起動すれば続きから始められます。

非対話モード（-p）で動かしたとき

プログラムの中や自動化の中でclaude -pを使った場合は、終了時の確認がないため、worktreeは自動では片付けられません。不要になったら自分でgit worktree removeを実行します。ロックがかかっていて削除を拒否された場合は、先にgit worktree unlockを実行します。

git worktree remove .claude/worktrees/feature-auth

Windowsでのリンクの扱い

Windowsでは、worktreeの中にあるフォルダが、別の場所へのリンク（NTFSのジャンクションやディレクトリのシンボリックリンク）になっていることがあります。worktreeを削除すると、リンクだけが消え、リンク先のフォルダは残ります。公式ドキュメントによると、v2.1.205より前のバージョンでは、サブフォルダの中にあるリンクのリンク先まで消えてしまう場合がありました。古いバージョンを使っているときは、更新してから使ってください。

設定のしかた

worktreeの作られ方は、既定のままでも多くの場面で足ります。必要に応じて、起点のブランチ、コピーするファイル、共有するフォルダなどを変えられます。

ブランチの起点を決める（baseRef）

新しいworktreeは、既定では、リポジトリの既定ブランチ（多くはmain）の、リモートの最新の状態から作られます。この動きは、設定のworktree.baseRefで変えられます。

設定は、プロジェクトの.claude/settings.jsonや、自分用の設定ファイルに書きます。

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

リモートが設定されていない場合や、既定ブランチの情報を取得できない場合は、現在のローカルのHEADから作られます。

.envなどの設定ファイルをコピーする（.worktreeinclude）

worktreeは新しいチェックアウトなので、Gitに入れていない.envのようなファイルはコピーされません。これを自動でコピーしたいときは、プロジェクトのルートに.worktreeincludeというファイルを作ります。書き方は.gitignoreと同じです。

.env
.env.local
config/secrets.json

コピーされるのは、このファイルに書いたパターンに一致し、かつ.gitignoreで除外されているファイルだけです。Gitで管理しているファイルが二重にコピーされることはありません。この設定は、--worktreeで作られるworktree、サブエージェントのworktree、デスクトップアプリの並行セッションのすべてに適用されます。

大きなフォルダの扱い（symlinkDirectories・sparsePaths）

プロジェクトが大きいと、worktreeを作るたびに時間とディスクを使います。次の2つの設定で軽くできます。

どちらも、初期状態では未設定です。sparsePathsを使うと、Gitがリポジトリの設定でextensions.worktreeConfigを有効にします。大きなリポジトリの扱い全般は、公式ドキュメントの「大きなコードベース」の章も参照してください。

worktreeと元のフォルダで共有されるもの

worktreeは別のファイルとブランチを持ちますが、次のものは元のプロジェクトと共有されます。

これらは、--worktreeで作った場合も、git worktree addで自分で作った場合も同じです。なお、フックのスクリプトで使う${CLAUDE_PROJECT_DIR}は、worktreeに移っても元のプロジェクトのルートを指したままです。worktreeの場所が必要なフックは、フックに渡される入力のcwdを読みます。

サブエージェント・デスクトップでの使い方

worktreeは、ターミナルで--worktreeを付けて起動する以外にも、いくつかの場面で自動的に使われます。

サブエージェントを専用のworktreeで動かす

サブエージェントを並行して動かすと、同じファイルを同時に編集して衝突することがあります。サブエージェントごとにworktreeを持たせれば、これを避けられます。Claudeに「エージェントにはworktreeを使って」と頼むか、自作のサブエージェントの定義にisolation: worktreeを書きます。

---
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の中で動きます。変更なしで終わったworktreeは自動で削除され、変更があったものは残ります。残ったworktreeは、後述する定期的な掃除の対象になります。

サブエージェントのworktreeも、--worktreeと同じ起点（既定ではリモートの既定ブランチ）から作られます。作業途中の変更を引き継がせたい場合は、先ほどのworktree.baseRefを"head"にします。

バックグラウンドのセッション

エージェントビューから依頼したセッションや、claude --bgで起動したセッションは、最初は現在のフォルダで始まります。ファイルを編集する前に、Claudeが自動で.claude/worktrees/の下のworktreeへ移ります。並行するセッションが同じチェックアウトを読めても、書き込みは別々のworktreeに行われます。

次のような場合は、worktreeへ移りません。

• 開いていたセッションを、←や/backgroundでバックグラウンドに回した場合（その場所で編集を続ける）
• すでにGitのworktreeの中で動いている場合
• 作業フォルダがGitのリポジトリではなく、WorktreeCreateフックも設定されていない場合

Gitのworktreeが使いにくいリポジトリでは、設定のworktree.bgIsolationを"none"にすると、バックグラウンドのセッションが元のフォルダを直接編集するようになります。既定は"worktree"です。

バックグラウンドのセッションが、worktreeの中でコードを変更した場合は、Claudeがセッションを終える前に、変更をコミットし、リモートがあればブランチをプッシュします。ただし、公式ドキュメントでは、mainへのプッシュ、強制プッシュ、マージは行わないと説明されています。コミットやプッシュを自分で行うとCLAUDE.mdなどに書いてある場合は、その指示が優先されます。

/batchで大きな変更を分担する

/batchは、1つの大きな変更を5〜30個のサブエージェントに分け、それぞれをworktreeで動かすスキルです。公式ドキュメントでは、サブエージェントとworktreeを組み合わせた使い方で、独立した調整方式ではないと説明されています。ファイル数の多い修正など、機械的に分けられる変更で使います。

デスクトップアプリで使う

Claudeのデスクトップアプリでは、画面の操作だけでworktreeを使えます。Gitのリポジトリでセッションを始めるとき、ブランチ名の隣にある「worktree」のオプションを選ぶと、そのセッションが専用のコピーで動きます。サイドバーの「＋ New session」からセッションを増やせるので、並行作業もマウスだけで進められます。

デスクトップアプリでも、.worktreeincludeは使えます。また、デスクトップアプリのworktreeセッションでは、設定・フック・スキルなどのプロジェクトの設定を、worktreeではなく元のフォルダのルートから読みます。CLAUDE.mdと.claude/rules/だけは、worktreeから読み込まれます。

Gitのコマンドで手動で作る

特定の既存ブランチから始めたいとき、worktreeをプロジェクトの外の場所に置きたいときは、Claude Codeを使わず、Gitのコマンドで自分で作れます。

新しいブランチを作って、worktreeを用意するコマンドです。

git worktree add ../project-feature-a -b feature-a

すでにあるブランチ（下の例ではfix-issue-456）からworktreeを作る場合は、次のようにします。

git worktree add ../project-bugfix fix-issue-456

作ったworktreeに移動して、Claude Codeを起動します。

cd ../project-feature-a
claude

いまあるworktreeの一覧はgit worktree listで確認でき、不要になったものはgit worktree remove ../project-feature-aで削除します。

手動で作ったworktreeは、Claudeが勝手に片付けません。裏を返せば、自分で作ったworktreeは、自分で削除するまで残るということです。使い終わったら、git worktree listで確認して整理しましょう。

Git以外のバージョン管理を使っている場合

SVN・Perforce・Mercurialなど、Git以外のバージョン管理を使っている場合は、WorktreeCreateとWorktreeRemoveのフックを設定して、作成と削除の処理を自分で用意します。フックが既定のGitの処理を置き換えるため、.worktreeincludeは処理されません。必要なファイルは、フックのスクリプトの中でコピーします。

フックは、作ったフォルダのパスを標準出力に出力します。Claude Codeはそのパスを、セッションの作業フォルダとして使います。フックが作るフォルダは、どのGitリポジトリの中にも入らない場所にしてください。リポジトリの中に作ると、Claude Codeがそのフォルダを使うのを拒否します。

注意点・困ったとき

使用量は並列の数だけ増える

worktreeを使うと、複数のセッションを同時に動かしやすくなります。公式ドキュメントでは、セッションやサブエージェントを同時に動かすと、トークン（AIが読み書きする文字量）の使用量が増えると案内されています。プランの上限に達しやすくなるので、並列にする数は、使用量を見ながら決めましょう。

worktreeの外には書き込めない

worktreeの中で動いているセッションは、元のフォルダ（メインのチェックアウト）を、うっかり書き換えないように守られています。Claude Codeは、次のような操作を止めます。

止められたときは、Claudeにエラーとして伝わり、書き直し方も示されます。ただし、これらのチェックは、コマンドが書き込むファイルまでは追跡しません。たとえばcpやシェルのリダイレクトで元のフォルダへ書き込む操作は、このチェックでは止まらず、通常の権限とサンドボックスの設定に従って扱われます。worktreeは、完全な隔離ではなく、事故を減らすための仕組みとして使うのが現実的です。

症状と対処

Git LFSの動きは、安全のための仕様です。フィルタはシェルのコマンドを実行できるため、リポジトリに書き込める何か（Claude自身を含む）が仕込んだものが実行されないように、リポジトリ自身の設定にあるフィルタは使われません。グローバルのGit設定にあるフィルタ（git lfs installだけで設定したもの）には影響しません。

会社で使うときに決めておくこと

複数のセッションを並行して動かせるようになると、「どのセッションが、どの変更をしたのか」が分かりにくくなります。チームで使うなら、次のような決めごとを先に共有しておくと、混乱を避けられます。

• worktreeの名前の付け方（例：機能名・fix-内容など、内容が分かる名前）
• Claude Codeが作るブランチを、どのタイミングでプッシュ・マージするか
• 終わったworktreeを、誰がいつ片付けるか
• .worktreeincludeに書いてよいファイルの範囲（秘密情報を含むファイルの扱い）
• 並列で動かすセッションの数の目安（使用量とレビューの負担を見て決める）

並行して進めた変更は、最終的に人がレビューして統合します。同時に動かせる数よりも、確認できる量の方が、実際の上限になります。

よくある質問

まとめ

worktreeは、1つのプロジェクトで複数の仕事を同時に進めるための基本の道具です。まずは、機能追加と不具合修正のように、触るファイルが重ならない2つの仕事を別のworktreeで頼むところから試してみてください。

社内の開発や業務ツールづくりにClaude Codeを使うときは、並列の使い方、ブランチの運用、権限の設定をあらかじめ決めておくと、安心して広げられます。INTERCREATE JAPANでは、Claude CodeやCodexの導入から、社内で使い続けられる運用の仕組みづくりまでをお手伝いしています。