Git Worktrees для ZCode

Каждый поток получает собственное рабочее дерево — автоматически. Git Worktrees выдаёт каждому новому потоку ZCode изолированную копию вашего репозитория, поэтому задачи выполняются параллельно без stash, переключения веток или перезаписи друг друга. Начинайте общение — вы уже изолированы.

/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 — и даже тогда несохранённые изменения сначала сохраняются в снимок (отслеживаемый diff + неотслеживаемые файлы) в восстанавливаемую директорию. Ветки по умолчанию сохраняются.

• Ваше окружение путешествует с вами. .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, node ≥ 18 в PATH, git.

Если /worktree не появляется: выполните node --version в терминале (MCP-серверу нужен node), убедитесь, что плагин включён в разделе «Установленные», и перезапустите ZCode, если вы установили его при открытом приложении.

Related MCP server: hop-mcp

Команды

За ними: девять MCP-инструментов (worktrees_create, worktrees_list, worktrees_status, worktrees_remove, worktrees_cleanup, worktrees_prune, worktrees_snapshot, worktrees_set_task, worktrees_auto_session), навык для модели и хуки — так что агент может использовать рабочие деревья самостоятельно, когда вы просите о параллельной или изолированной работе.

Автоматические рабочие деревья для сессий (включено по умолчанию)

Каждая новая сессия в основном checkout репозитория получает собственное рабочее дерево (zcode/sess-…); при возобновлении вы возвращаетесь в то же самое, а правки файлов в основном checkout блокируются и перенаправляются в рабочее дерево сессии. Переключите в Настройки → Плагины → 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 блокируются против основного checkout с помощью PreToolUse-защиты; Bash направляется внедрённым контекстом, а не статически контролируется.

• У ZCode нет события окончания сессии, поэтому при выходе ничего не коммитится и не удаляется автоматически — /worktree:end является явной финишной чертой, а периодическая очистка собирает то, что осталось бездействующим.

• Задержка в одну сессию для изменений настроек автоматической сессии (хуки читают маркер, который MCP-сервер синхронизирует при запуске сессии).

Лицензия

MIT © Alfredo Gallardo