Git Worktrees 用 ZCode

すべてのスレッドは独自のワークツリーを取得します — 自動的に。Git Worktrees は、新しい ZCode スレッドごとにリポジトリの分離されたチェックアウトを提供するため、スタッシュやブランチの切り替え、相互の上書きなしでタスクを並行して実行できます。チャットを開始するだけで、すでに分離されています。

/worktree:new fix-auth "Refactor the login flow"   ← worktree + background agent
/worktree                                          ← dashboard: branches, sizes, agents
/worktree:end fix-auth                             ← commit everything, remove cleanly

なぜ必要なのか

• ゼロセットアップ。 自動セッションモード（デフォルトでオン）は、新しいスレッドが開始された瞬間に独自のワークツリーを提供し、スレッドを再開すると同じワークツリーに戻ります。コマンドは一切不要です。

• 作業を失わない。 ダーティなワークツリー、実行中のエージェント、または未マージのブランチの削除は、force なしでは拒否されます。それでも、未コミットの変更は最初にスナップショット（追跡された差分 + 追跡されていないファイル）が復元可能なディレクトリに保存されます。ブランチはデフォルトで保持されます。

• 環境は一緒に移動します。 .env など（gitignore され、.worktreeinclude にリストされているもの）は新しいワークツリーに持ち込まれます。setupCommands（pnpm install、docker compose up -d）は自動的に実行されます。

• 邪魔になりません。 ワークツリーは中央ストア（~/.zcode/worktrees）に置かれ、リポジトリは元のまま保たれ、保持スイープによりディスク使用量が制限されます。何も黙って削除されることはありません。

インストール

1. ZCode Desktop で、設定 → プラグイン管理 を開き、マーケットプレイスを追加 をクリックします。

2. リポジトリを貼り付けます — GitHub の owner/repo スラッグまたは完全な Git URL のどちらでも機能します：

   agallardol/zcode-git-worktrees

3. カタログから Git Worktrees をインストールします。

4. 任意の git リポジトリを開いてスレッドを開始します — すでに分離されています。ダッシュボードには /worktree と入力します。

要件: ZCode ≥ 3.8.1、PATH 上の node ≥ 18、git。

/worktree が表示されない場合: ターミナルで node --version を実行し（MCP サーバーには node が必要）、インストール済みの下でプラグインが有効になっていることを確認し、アプリが開いている間にインストールした場合は ZCode を再起動します。

Related MCP server: hop-mcp

コマンド

その背後には、9 つの MCP ツール（worktrees_create、worktrees_list、worktrees_status、worktrees_remove、worktrees_cleanup、worktrees_prune、worktrees_snapshot、worktrees_set_task、worktrees_auto_session）、モデル向けスキル、フックがあります。これにより、並列または分離された作業を依頼すると、エージェントが独自にワークツリーを使用できます。

自動セッションワークツリー（デフォルトでオン）

リポジトリのメインチェックアウトでの新しいセッションごとに、独自のワークツリー（zcode/sess-…）が作成されます。再開すると同じワークツリーに戻り、メインチェックアウトへのファイル編集はブロックされ、セッションワークツリーにリダイレクトされます。設定 → プラグイン → Git Worktrees または /worktree:auto で切り替えます（最後の変更が優先されます）。リポジトリはいつでもオプトアウトできます：

// .zcode/worktree.json in the repo
{ "autoSession": false }

リポジトリ側の設定（オプション）

.worktreeinclude — gitignore スタイルのパターン。また gitignore されているファイルのみが新しいワークツリーに持ち込まれます（追跡されたファイルは決して複製されません）：

.env
config/secrets.json

.zcode/worktree.json — 明示的なファイル、ライフサイクルフック、自動セッションのオーバーライド：

{
  "autoSession": true,
  "copyFiles": [".env.local"],
  "setupCommands": ["pnpm install"],
  "preRemoveCommands": ["docker compose down"]
}

プラグイン設定（設定 → プラグイン → Git Worktrees）: ワークツリールート、デフォルトベース（fresh = オフラインフォールバック付きの origin/HEAD、または head）、最大経過日数（14）、プロジェクトごとの最大ワークツリー数（15）。

安全モデル

• ストアから逃げ出さない — 名前はパスと git-ref の安全性について検証され（トラバーサル、.lock、ケースツイン、ユニコードのトリックはすべて拒否）、フルパスはシンボリックリンクに対して保護され、ストアパスは正規化されます。git worktree add が失敗すると、そのブランチはロールバックされます。

• 並行性安全 — 変更はプロセス内キューとプロセス間ロックファイルによって直列化されます。並列作成で状態が失われることはありません。

• 自己修復 — 破損した状態は隔離されて再構築され、ワークツリーは git から再採用され、帯域外の削除は prune/cleanup によって調整されます。

• 信頼できないリポジトリからの実行なし — setupCommands / preRemoveCommands は、明示的に作成したワークツリーでのみ実行されます。自動セッションの作成では、リポジトリ提供のコマンドは決して実行されません。クローンされたリポジトリを開くことはコード実行ではありません。すべての git 呼び出しは execFile を経由します。シェル実行は、オプトインしたライフサイクルコマンドのみです。

インスピレーションを得たツールと比較すると、PR 番号チェックアウトと .worktreeinclude のセマンティクスは Claude Code から、削除前スナップショットと中央ストアは Codex から、制限付き保持は Cursor/Codex から来ています。さらに、バックグラウンドエージェントのタスクオーケストレーションとハードな編集分離は、どれもプラグインに公開していません。

テスト

npm test   # 129 tests: 80 unit (validators, state, carry-over, hooks, edit guard)
           #        + 13 integration (real MCP stdio JSON-RPC + protocol edges)
           #        + 36 adversarial & security (hostile names, races, corrupt
           #           state, out-of-band damage, exploit regressions)

CI runs the suite on macOS and Linux (Node 20 and 22).

スイートは完全にローカルフィクスチャに対して実行されます — ネットワークもモデル呼び出しもありません。

注意事項と制限

• 自動セッションの分離は、コマンドにはソフト、編集にはハードです。Write/Edit ツールは PreToolUse ガードによってメインチェックアウトに対してブロックされます。Bash は注入されたコンテキストによってガイドされ、静的に監視されるわけではありません。

• ZCode にはセッション終了イベントがないため、終了時に自動コミットや削除は行われません。/worktree:end が明示的な終了ラインであり、保持スイープがアイドル状態のものを収集します。

• 自動セッションの設定変更には 1 セッションの遅延があります（フックは MCP サーバーがセッション開始時に同期するマーカーを読み取ります）。

ライセンス

MIT © Alfredo Gallardo