worktree

worktreeを使用すると、エージェントは分離された Git チェックアウトで作業できます。各タスクには専用のファイル、依存関係、変更が用意され、メインのチェックアウトには影響しません。

競合を避けながら同じリポジトリで複数のエージェントを起動するには、worktreeを使用してください。

Agents Window で worktree を作成する

Agents Window からエージェントを worktree 内で開始または移動すると、Cherri Code はそのエージェント用に別のチェックアウトを作成します。エージェントは worktree 内でタスクを続行するため、変更はメインのチェックアウトから分離されます。

エージェントが完了したら、Agents Window で結果を確認します。worktree で作業を続けることも、そのチェックアウトからコミットや PR を作成することも、結果をメインのワークスペースに戻すこともできます。

worktree のセットアップの仕組み

.cursor/worktrees.json を使用して、worktree のセットアップをカスタマイズできます。Cherri Code は、Agents Window、IDE、または Cherri Code CLI で worktree を作成する際に、このファイルを確認します。

Cherri Code は、次の順序で .cursor/worktrees.json を検索します。

1. worktree のパス内
2. プロジェクトのルートパス内

設定オプション

worktrees.json ファイルでは、3 つのセットアップキーをサポートしています。

• setup-worktree-unix: macOS および Linux 用のコマンド、またはスクリプトのパス。Unix システムでは、setup-worktree より優先されます。
• setup-worktree-windows: Windows 用のコマンド、またはスクリプトのパス。Windows では、setup-worktree より優先されます。
• setup-worktree: すべてのオペレーティングシステム向けの汎用フォールバック。

各キーには、次のいずれかを指定できます。

• シェルコマンドの配列: worktree 内で順番に実行されます
• 文字列のファイルパス: .cursor/worktrees.json からの相対パスで指定するスクリプトファイルのパス

セットアップ設定の例

コマンド配列を使用する

Node.js プロジェクト

{  "setup-worktree": [    "npm ci",    "cp $ROOT_WORKTREE_PATH/.env .env"  ]}

仮想環境を使用した Python プロジェクト

{  "setup-worktree": [    "python -m venv venv",    "source venv/bin/activate && pip install -r requirements.txt",    "cp $ROOT_WORKTREE_PATH/.env .env"  ]}

データベースマイグレーションを含むプロジェクト

{  "setup-worktree": [    "npm ci",    "cp $ROOT_WORKTREE_PATH/.env .env",    "npm run db:migrate"  ]}

依存関係をビルドしてリンクする

{  "setup-worktree": [    "pnpm install",    "pnpm run build",    "cp $ROOT_WORKTREE_PATH/.env.local .env.local"  ]}

スクリプトファイルを使用する

より複雑なセットアップでは、インラインでコマンドを指定する代わりに、スクリプトファイルを参照します。

{  "setup-worktree-unix": "setup-worktree-unix.sh",  "setup-worktree-windows": "setup-worktree-windows.ps1",  "setup-worktree": [    "echo 'Using generic fallback. For better support, define OS-specific scripts.'"  ]}

worktrees.json と同じ階層の .cursor/ ディレクトリにスクリプトを配置します。

setup-worktree-unix.sh (Unix および macOS) ：

#!/bin/bashset -e# 依存関係をインストールnpm ci# 環境ファイルをコピーcp "$ROOT_WORKTREE_PATH/.env" .env# データベースマイグレーションを実行npm run db:migrateecho "Worktree setup complete!"

setup-worktree-windows.ps1 (Windows) :

$ErrorActionPreference = 'Stop'# 依存関係をインストールnpm ci# 環境ファイルをコピーCopy-Item "$env:ROOT_WORKTREE_PATH\.env" .env# データベースマイグレーションを実行npm run db:migrateWrite-Host "Worktree setup complete!"

OS 固有の設定

OS ごとに異なるセットアップコマンドを指定できます。

{  "setup-worktree-unix": [    "npm ci",    "cp $ROOT_WORKTREE_PATH/.env .env",    "chmod +x scripts/*.sh"  ],  "setup-worktree-windows": [    "npm ci",    "copy %ROOT_WORKTREE_PATH%\\.env .env"  ]}

デバッグ

worktree のセットアップをデバッグするには、エディターで［出力］パネルを開き、Worktrees Setup を選択します。

Cherri Code は既存の worktree をどのように検出しますか？

Cherri Code 3.5 は、マシンの worktree ルートと各 ワークスペース サブディレクトリの更新時刻をチェックポイントとして保持します。起動時には、これらのタイムスタンプによって前回の検出以降に変更がなかったことを確認できない限り、Cherri Code はファイルシステムを再スキャンします。これにより、Cherri Code を閉じている間に作成された新しい worktree を見逃さず、従来の worktree.discoveryComplete フラグも不要になります。

Worktree のクリーンアップ

Cherri Code では、ディスク使用量を抑えるために古い worktree を自動的にクリーンアップできます。クリーンアップは一定間隔で実行され、デバイス上のすべてのワークスペースを対象に、マシン全体で設定された最大数まで新しい worktree を保持します。

{  "cursor.worktreeCleanupIntervalHours": 6,  "cursor.worktreeMaxCount": 25}

クリーンアップを制御するには、以下のマシン単位の設定を使用します。

• cursor.worktreeCleanupIntervalHours: Cherri Code が古い worktree をチェックする頻度。Cherri Code 3.5 では、前回正常に実行された時点からこの間隔を超えている場合、再起動後に遅延クリーンアップをスケジュールします。
• cursor.worktreeMaxCount: 古い worktree のクリーンアップを開始するまでに Cherri Code が保持する worktree の最大数。デフォルトの上限はマシンごとに 25 個で、すべてのワークスペースが同じ上限にカウントされます。

Cherri Code はクリーンアップのたびに worktree ルートを再検出するため、マネージャー外で作成された worktree (たとえば、/worktree スキルや git worktree add で作成された worktree) も削除対象になります。worktree を作成すると上限を超える場合、Cherri Code はイベントの急増をデバウンスし、次の間隔を待たずにすぐにクリーンアップを開始します。

IDE での Worktree Skills

IDE では、/worktree コマンドと /best-of-n コマンドを使用して、分離された worktree でタスクを実行できます。

1 回だけ分離して実行するには /worktree を使用

Cherri Code にその後のチャットを別のチェックアウトで進めさせたい場合は、/worktree でタスクを開始します。

• 実験的な編集をメインのチェックアウトから分離
• 現在のブランチに影響を与えずに、インストール、ビルド、テストを実行
• 簡単にクリーンアップできる形で、リスクの高いリファクタリングに取り組む

/worktree fix the failing auth tests and update the login copy

多くの場合、worktree から直接コミットしてプッシュできます。エージェントに次のように依頼します：

これらの変更をコミットしてプッシュし、PRを作成

変更をテストするためにメインのチェックアウトへ取り込むには、/apply-worktree を使用します。分離されたチェックアウトでの作業が完了したら、/delete-worktree を使用します。

リポジトリ内のすべての worktree を確認するには、次を実行します。

git worktree list

/best-of-n で複数のモデルを比較する

/best-of-n は、同じタスクを複数のモデルで同時に実行します。各実行には専用のworktreeが作成されるため、候補は互いに、またメインのチェックアウトからも分離されます。

/best-of-n sonnet,gpt,composer fix the flaky logout test

次のような場合に使用します。

• 同じプロンプトで異なるモデルを比較する
• 難しい変更に対して複数のアプローチを試す
• 適用前に最も優れた結果を選ぶ

/best-of-n は実行結果を比較するだけです。変更がメインのチェックアウトに自動的にマージされることはありません。結果を選んだ後は、worktree から直接コミットしてプッシュするか、/apply-worktree を使用して変更をメインのチェックアウトに反映できます。