Claude Code Worktree — git-изоляция для непересекающихся параллельных агентов
На 2026-10-20 Claude Code изолирует параллельные сессии через git worktree: claude --worktree feature-auth создаёт дерево в .claude/worktrees/ с веткой worktree-feature-auth; субагенты могут задать isolation: worktree. При выходе Claude проверяет, что будет потеряно.
Что такое worktree и зачем он нужен
git worktree — дополнительный рабочий каталог того же репозитория с собственными файлами и веткой, который делит историю .git и remote с основным checkout. Claude Code запускает каждую параллельную сессию в своём worktree: claude --worktree feature-auth (или -w) создаёт .claude/worktrees/feature-auth/ в корне репозитория с веткой worktree-feature-auth. Сессия A пишет фичу X, сессия B чинит баг Y, и файлы не пересекаются.
Инструмент EnterWorktree и конфиг isolation
В сессии можно попросить Claude работать в worktree — он создаст его инструментом EnterWorktree. Вход в путь вне .claude/worktrees/ требует подтверждения (до v2.1.206 Claude мог войти в любой существующий worktree без вопроса). Кастомному субагенту достаточно добавить isolation: worktree во frontmatter, чтобы каждый запуск получал временный worktree. Добавьте .claude/worktrees/ в .gitignore, а .worktreeinclude перенесёт .env и другие игнорируемые файлы в новые worktree.
Worktree субагентов и параллельные агенты
Субагенты могут работать каждый в своём worktree: попросите Claude «use worktrees for your agents» или добавьте isolation: worktree кастомному субагенту. Каждый получает временный worktree, который автоматически удаляется, если работа завершена без изменений; worktree с изменениями остаётся на диске, пока периодическая очистка не сможет удалить его без потери работы. Пример: три агента одновременно переписывают auth, добавляют юнит-тесты и пишут миграции — файлы не сталкиваются, merge выполняется в конце.
Автоочистка, типовые ошибки, командные соглашения
Когда вы выходите из интерактивной сессии worktree, Claude проверяет изменённые и неотслеживаемые файлы и новые коммиты: чистая безымянная сессия удаляется автоматически, для именованной Claude сначала спрашивает, а при наличии изменений предлагает оставить или удалить worktree; запуски с -p автоматически не очищаются. Частые ошибки: 1) конфликты имён веток между агентами; 2) worktree субагентов с изменениями остаются на диске до периодической очистки; 3) забыли добавить .claude/worktrees/ в .gitignore. Договоритесь в команде о фиксированном префиксе веток (например, wt/agent-<name>-<ts>), чтобы избежать конфликтов.
FAQ
Чем worktree отличается от обычной ветки git?
Ветка — это указатель на коммит; переключение требует checkout и перезаписывает файлы. Worktree — отдельный рабочий каталог, поэтому несколько веток можно одновременно checkout в разные физические пути. Это и есть основа параллельной работы агентов.
Не загрязняют ли worktree субагентов основной репозиторий?
Нет. Каждый субагент получает временный worktree; git ведёт их в .git/worktrees/<id>. Worktree субагента без изменений удаляется автоматически, а с изменениями остаётся до очистки, которая удалит его без потери работы; основной checkout остаётся чистым.
Можно ли использовать worktree с Claude Code из Китая?
Да. Worktree — локальная функция git и клиента Claude Code; вывод модели идёт через настроенный эндпоинт QCode. Worktree требует git-репозитория; для других систем контроля версий настройте WorktreeCreate и WorktreeRemove hooks вместо git-логики.
Связанные руководства
Запускайте параллельных агентов Claude Code через QCode
Вывод модели идёт через API-эндпоинт QCode, а worktree работает локально; параллельные сессии запускаются командами выше.
Подключить план QCode