「Claude Code の worktree」と聞くと、有効化する機能のように思えます。ほとんどの場合、話はもっと単純です。worktree は git が作るディレクトリであり、Claude Code は起動したディレクトリのファイルを編集するプロセスです。この 2 つを組み合わせれば、エージェントセッションが分離されます。
この区別が大事なのは、インターネット上で 3 つの異なるものが混同されているからです。git worktree、Claude Code のアプリ内部の worktree 機能、そして worktree を代わりに作ってくれるワークスペースツールです。名前と目的は共通していますが、ディレクトリを作ったのが誰かによって、場所、後片付け、レビューの話が変わります。
git worktree とは何か
通常の clone には作業ツリーが 1 つあります。エディタに見えているファイルです。git worktree を使うと、同じリポジトリが複数の作業ツリーを同時に持てます。それぞれ別のブランチです。オブジェクトデータベースとリモートは共有されますが、チェックアウトされたファイルとインデックスは共有されません。
git worktree list
# /Users/you/app abc1234 [main]
# /Users/you/app-fix-login def5678 [fix/login]- 各 worktree は独自のブランチ、HEAD、インデックス、ディスク上のファイルを持つ。
- 同じブランチを 2 つの worktree で同時にチェックアウトすることはできない。
- worktree を削除すると、ディレクトリとチェックアウトが消える。ブランチの履歴は消えない。
- どの worktree も同じリポジトリなので、commit、fetch、push は同じオブジェクトを見る。
これこそエージェントに必要な分離です。Claude Code は自分が開いているチェックアウトに触れずに、worktree 内で読み、編集し、テストを実行し、commit できます。エージェントが何かを壊したら、そのディレクトリを削除してメインブランチを残せばよいのです。
Claude Code に worktree が向いている理由
エージェントセッションは、たまたまファイルに触るチャットではありません。コマンドを実行し、開発サーバーを起動し、生成ファイルを書き、変更をステージし、ときにはブランチを切り替えます。1 つのチェックアウトで 2 つのセッションを動かせば、その状態をすべて共有します。失敗は劇的でないことが多いものです。テストが間違ったコードに対して通り、フォーマッタが別のエージェントの作業を書き換え、commit に両方のタスクのファイルが混ざります。
worktree は、そうした共有状態の失敗を別々のディレクトリに変えます。代償は、新しい worktree がきれいな状態から始まることです。node_modules も .env もローカルデータベースもありません。このガイドの残りは、その代償を意識的に払う方法が中心です。
Claude Code に worktree モードはあるのか
Claude Code の CLI は、worktree で動くために特別なモードを必要としません。セッションの境界は作業ディレクトリです。../app-fix-login の中で claude を起動すれば、セッションはそこで読み書きします。../app-fix-billing の中で別のセッションを起動すれば、別のブランチと別のファイル群になります。
Claude Code の他の画面では、worktree を代わりに管理してくれます。デスクトップアプリは隔離された git worktree で並列セッションを実行でき、エージェントチームやサブエージェントはセッション内で作業を委任できます。これらは便利なレイヤーで、チェックアウトを作り、エージェントをその中に入れ、パスを隠します。場所を予測可能にしたいなら、自分で worktree を作り、その中で Claude Code を起動してください。
Claude Code の worktree はどこに置くべきか
場所は worktree を作る人によって変わります。手動でセットアップするなら、git worktree add にパスを渡します。うまく機能する慣習は 2 つあります。メインのチェックアウトの隣に兄弟ディレクトリとして置くか、リポジトリの外の専用 worktrees/ フォルダに置くかです。
# sibling next to the main checkout
git worktree add ../app-fix-login -b fix/login origin/main
# or a dedicated root outside the repo
git worktree add ~/worktrees/app/fix-login -b fix/login origin/mainworktree はメインのチェックアウトの外に置きましょう。リポジトリ内の worktree はすべての検索に現れ、エディタのインデックスを混乱させ、誤って commit される可能性があります。ツールがリポジトリ内の隠しフォルダに worktree を作る場合は、そのフォルダが gitignore されているか確認してから頼りにしてください。
Nethür は独自の管理ディレクトリに worktree を作り、パスを追跡します。Claude Code、GSD、素の git worktree add で作った既存の worktree がある場合、Nethür は移動を求める代わりに外部 worktree として表示できます。設定 → 一般 → ワークスペースで、どの外部ソースを表示し、どの場所のルートをスキャンするかを制御できます。
パスを手で管理したくない場合は、Nethür のような git worktree の GUI が、ディスク上には通常のチェックアウトを残したまま、worktree の作成・追跡・削除を代行します。
worktree を作成して Claude Code を起動する
エージェントが先週のコードに向かわないよう、最新のベース ref から始めます。
git fetch origin
git worktree add ../app-fix-login -b fix/login origin/main
cd ../app-fix-login
claudeworktree ごとに一意のブランチ名を使います。同じタスクに 2 つ目のエージェントを置きたい場合は、プロンプトが同じでも別のブランチで 2 つ目の worktree を作ります。ブランチがあるからこそ、2 つの結果を比較し、独立して merge できるのです。
Nethür では同じ手順がダイアログになります。worktree を作成し、タスクに名前を付け、開始元の ref を選び、エージェントを選択します。Nethür がバックグラウンドで git fetch と git worktree add を実行し、作成中もワークスペースを表示し、新しいチェックアウトでエージェントを開きます。worktree のドキュメント では、開始元ピッカー、フォルダワークスペース、リンクされた issue を説明しています。
依存関係、env ファイル、ポート
新しい worktree はきれいなチェックアウトなので、git が無視するものはすべて欠けています。対処法は 3 つあり、ほとんどのチームは最終的に 3 つとも使います。
- worktree ごとにインストールする。正しくて単純ですが、すべてのエージェントが自分の
node_modulesを必要とすると遅く、ディスクを圧迫します。 - 重くて再生成できるディレクトリを共有する。Nethür の Worktree Shared Paths は、プライマリのチェックアウトから gitignore されたディレクトリを実体化します。リポジトリ単位の定義には
nethur.yamlのworktree.sharedDirectoriesを使います。 - 小さく worktree 固有のファイルをコピーする。
.worktreeincludeに gitignore されたファイルやディレクトリ(.envやローカルのエディタ設定など)を列挙し、各 worktree が自分のコピーを持ちます。
# nethur.yaml at the repo root
worktree:
sharedDirectories:
- node_modules
- .cache
# .worktreeinclude at the repo root
.env
.env.local
.vscode/settings.jsonポートには独自のルールが必要です。2 つのエージェントが同じ開発サーバーを起動すると、2 つ目は失敗するか、さらに悪いことに 1 つ目のデータベースに接続します。ポートとデータベース名を worktree ごとの環境ファイルに書くか、セットアップフックで worktree 名から導出させます。
diff をレビューしてから worktree を削除する
各 worktree は、今の main ではなく、開始元の ref と比較してレビューします。そうすれば diff はエージェントの作業に集中できます。Nethür はワークスペースごとに diff を表示し、インライン注釈に対応し、commit 前にレビューメモをエージェントへ返せます。
作業が merge されたら、worktree とブランチを削除します。ディレクトリを手で削除しないでください。git は .git/worktrees 以下にメタデータを保持しているので、手動の rm -rf は古いエントリを残します。
git worktree remove ../app-fix-login
git branch -d fix/login
# if git refuses because the branch has unmerged commits
git worktree remove --force ../app-fix-loginworktree が消えた後も、git は未 merge の commit を含むローカルブランチを残すことがあります。これは安全網であってバグではありません。Nethür は残されたブランチをレビュー手順で表示するので、後から探し回るのではなく、どれを強制削除するかを決められます。
worktree でよくある間違い
- 同じブランチを 2 つの worktree でチェックアウトする。git が拒否します。2 つ目のエージェントには別のブランチを選びましょう。
- worktree をリポジトリの中に置く。検索やエディタに重複ファイルが見え、そのディレクトリが commit される可能性もあります。
- メインのデータベースを指す 1 つの
.envを共有する。マイグレーションが絡むなら、各エージェントに専用のデータベースかスキーマを与えるべきです。 - ベース ref を忘れる。古いローカルブランチから作った worktree は、紛らわしい diff と苦痛な merge を生みます。
- 実験の後に何十もの worktree を開いたままにする。どれが勝ったか覚えているうちにブランチを片付けましょう。
チームでの worktree
チームサーバーでは、worktree は個人のディレクトリではなくなります。共有のプロジェクト状態です。チームメイトは、worktree が存在すること、誰が作ったか、どのエージェントが動いているか、ブロックされているかどうかを見られます。この可視性が、安全に作業を渡せる理由です。
Nethür は、ノート PC、チームメイトのマシン、VPS、SSH の接続先のどこで動いていても、同じ worktree モデルを保ちます。エージェントはチェックアウトがある場所で動き、クライアントはセッションを描画するだけです。この構成のチーム版を知りたい方は、チーム向け Claude Code をお読みください。
1 つのタスクで試してみる
小さな変更のために worktree を 1 つ作り、その中で Claude Code を起動し、メインのチェックアウトを隣に開いたままにします。2 つのセッションが干渉しなくなれば、余分なディレクトリは負担に感じなくなります。並列エージェントガイド では、これを複数エージェントに広げ、結果を比較する方法を紹介しています。



