Nethür
ログイン
macOS 版は近日公開

ブログ · 2026年11月5日

Claude Code の worktree を理解する

Claude Code における git worktree を平易に解説。何を分離するのか、どこに置くのか、作業を失わずに作成・レビュー・削除する方法を紹介します。

1 つの main ブランチがタスクごとに 3 つの Nethür worktree に分かれる図

Claude Code の worktree とは、その中で Claude Code を動かす普通の git worktree です。Git がリポジトリの 2 つ目のコピーを別ブランチでチェックアウトし、Claude Code はそのディレクトリを作業ツリーとして使います。メインのチェックアウトはそのまま残ります。場所は `git worktree add` に渡したパス、またはその作業を代行してくれるツールの管理ディレクトリになります。

「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/main

worktree はメインのチェックアウトの外に置きましょう。リポジトリ内の 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
claude

worktree ごとに一意のブランチ名を使います。同じタスクに 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-login

worktree が消えた後も、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 つのセッションが干渉しなくなれば、余分なディレクトリは負担に感じなくなります。並列エージェントガイド では、これを複数エージェントに広げ、結果を比較する方法を紹介しています。

ガイドを実践に。

Nethür をダウンロードすれば、数分で最初の並列エージェントを動かせます。すでに持っているマシンでチームワークスペースを立ち上げることもできます。