Запуск параллельных сеансов с worktrees

​

Запустите Claude в worktree

claude --worktree feature-auth

​

Настройте окружение worktree

​

Попросите Claude создать worktree

​

У Claude нет инструмента EnterWorktree

• Интерактивные сессии: запустите сессию в worktree с помощью claude --worktree.
• Фоновые сессии: Claude Code отклоняет правки фоновой сессии в вашей основной копии, пока сессия не вызовет EnterWorktree, которого у неё нет. Любой из следующих способов позволяет сессии вносить правки:
  • Запустите её с помощью claude --bg --worktree
  • Установите для worktree.bgIsolation значение "none"
  • Попросите Claude вносить правки в worktree, созданном с помощью git worktree add внутри каталога, в котором была запущена сессия

​

Очистка worktrees

• Worktree чист: для безымянного сеанса Claude автоматически удаляет worktree и его ветку. Именованный сеанс сначала предлагает вам, чтобы вы могли сохранить worktree на потом
• Worktree содержит работу: Claude предлагает вам сохранить или удалить worktree. Сохранение сохраняет каталог и ветку. Чтобы вернуться позже, запустите команду claude --worktree <name> --resume, которую Claude Code выведет при выходе. Удаление удаляет каталог worktree и его ветку, вместе со всей работой в них
• Извлечена другая ветка: если worktree находится на ветке, отличной от его собственной, и в ней есть коммиты после начального коммита worktree, Claude предлагает вам сохранить или удалить worktree. При любом ответе эта другая ветка и её коммиты сохраняются. Удаление удаляет каталог worktree и собственную ветку worktree — ту, которую Claude создал вместе с ним
• Состояние worktree не может быть проверено: когда Claude Code не может подсчитать изменения worktree или не может проверить проверки его подмодулей, он предлагает вам вместо автоматического удаления worktree. Подсказка указывает, что он не смог проверить

​

Возобновите сеанс worktree

• Каталог запуска: возобновите с помощью --resume из основной копии или другого каталога репозитория. Claude Code повторно входит в worktree, который он создал с git в .claude/worktrees/, даже когда вы запускаете из него. Когда вы запускаете из любого другого worktree, Claude Code повторно входит в него только если может поручиться за него оттуда: worktree, который является его собственным репозиторием, один без метаданных git, или запуск из подкаталога worktree, который вы создали с git worktree add, отказывает, поэтому запускайте их из основной копии.
• --fork-session: разветвлённый сеанс начинается в каталоге, из которого вы запустили Claude, и Claude Code оставляет worktree исходного сеанса нетронутым.
• Удалённый worktree: если каталог worktree больше не существует, Claude Code возобновляет сеанс в каталоге, из которого вы запустили Claude. Он сообщает вам, что worktree исчез, и очищает привязку worktree сеанса.

​

Как Claude Code обеспечивает изоляцию

• Правки файлов: Claude Code блокирует Edit, Write или NotebookEdit, который нацелен на путь в основной копии. Чтобы изменить файл в основной копии, отредактируйте его самостоятельно или запустите там интерактивную сессию.
• Рабочий каталог команды: Claude Code блокирует команду Bash, PowerShell или Monitor, чей рабочий каталог разрешается в основную копию, или чей рабочий каталог он не может проверить, остаётся вне неё.
• Перенаправления git: Claude Code блокирует команду Bash или Monitor, которая перенаправляет git в основную копию. Перенаправление может поступать через git -C, --git-dir, переменную GIT_DIR или GIT_WORK_TREE или cd в основную копию перед запуском git.
• Форма команды: Claude Code блокирует команду Bash или Monitor, когда он не может проверить из текста команды, что любой git, который запускает команда, остаётся внутри worktree. Это происходит, например, когда имя команды вычисляется во время выполнения, когда синтаксис не может быть проанализирован, или когда расширение, такое как ${!name} или ${ command; }, может запустить команду, которую текст не указывает явно. Claude Code сообщает Claude, как переписать отказанную команду, например разделив её на простые отдельные команды. Вы не можете отключить эту проверку.

​

Изолируйте subagents с помощью worktrees

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---

Apply the requested refactor across every affected file, then run the tests
and report the results.

​

Очистка worktrees subagent и фоновых сеансов

• Worktree по-прежнему содержит работу: изменённые или неотслеживаемые файлы или неотправленные коммиты.
• Извлечённый submodule в worktree содержит изменённые или неотслеживаемые файлы, или Claude Code не может проверить submodules worktree. Эта проверка требует Claude Code v2.1.274 или более позднюю версию.
• Один из четырёх случаев, которые также блокируют создание worktree применяется: Claude Code не может определить, какие драйверы фильтров определяет конфигурация репозитория, или находит там параметр, который не может отключить.
• Worktree принадлежит сеансу --worktree, который вы не отправили в фон, независимо от его возраста.
• Вы создали worktree самостоятельно с git worktree add, даже если вы затем запустили сеанс --worktree <name> в нём и отправили этот сеанс в фон.

​

Блокировки worktree и ручное удаление

​

Настройка создания worktree

​

Выбор базовой ветки

• "fresh" (по умолчанию): ответвление от ветки по умолчанию репозитория на удалённом сервере, обычно main, чтобы worktree начинался с чистого дерева, совпадающего с удалённым.
• "head": ответвление от вашего текущего локального HEAD, чтобы worktree содержал ваши неотправленные коммиты и состояние feature-ветки. Используйте это значение при изоляции субагентов, которым нужно работать с незавершённой работой. Внутри worktree "head" указывает на HEAD этого worktree, а не основного checkout.

• Если репозиторий не получал обновления в течение последних 24 часов, Claude Code выполняет fetch ветки по умолчанию с ограничением в пять секунд и использует локально кэшированную ссылку, если fetch завершился неудачно.
• Fetch никогда не ожидает ввода в вашем терминале. Он также считается неудачным, если git или ssh запросили бы пароль, парольную фразу ключа или подтверждение нового SSH-хоста.
• Если удалённый репозиторий не настроен либо origin/HEAD не кэширован локально и не может быть получен, worktree создаётся от вашего текущего локального HEAD.

{
  "worktree": {
    "baseRef": "head"
  }
}

​

Ответвление от pull request

claude --worktree "#1234"

• github.com: получает pull/<number>/head
• gitlab.com: получает merge-requests/<number>/head
• GitHub Enterprise, самостоятельно размещённый GitLab или любой другой хост: сначала пробует pull/<number>/head, затем merge-requests/<number>/head

​

Копирование игнорируемых git файлов в worktree

.env
.env.local
config/secrets.json

​

Повторное использование имени worktree

• В нём нет незакоммиченных изменений или неотслеживаемых файлов.
• Он по-прежнему находится на ветке, которую Claude Code создал для него.
• В нём нет собственных коммитов, либо его pull request или merge request был слит, а удалённая ветка удалена.

• Worktree не удовлетворяет какому-либо из условий.
• Claude Code не может проверить состояние worktree.
• worktree.baseRef имеет значение "head".
• Имя является ссылкой на pull request или merge request.

​

Замена создания worktree хуком

​

Что worktrees делят с основной копией

• Каталог .git репозитория: команды git в worktree записывают в общий каталог .git основного репозитория. При включённой песочнице команды, такие как git commit, работают в сессии, запущенной в корне worktree, — именно там её запускает --worktree. По умолчанию они завершаются с ошибкой index.lock, если вы запускаете claude в подкаталоге worktree.
• Плагины: плагины, установленные на уровне проекта из основной копии, также загружаются в worktrees того же репозитория, поэтому вам не нужно переустанавливать их для каждого worktree.
• Подтверждения разрешений: выбор “Yes, and don’t ask again” для команды Bash в сессии worktree сохраняет правило в .claude/settings.local.json основной копии. Правило применяется в основной копии и в каждом другом worktree репозитория и сохраняется после удаления worktree. На Windows и в других случаях, когда Claude Code не использует корень репозитория, правило остаётся с этим worktree. См. где сохраняются подтверждения.
• Неотслеживаемые skills, agents и commands: когда копия worktree не имеет каталога .claude/skills в своём корне, например потому что ваш .claude/skills находится в gitignore, Claude Code загружает project skills основной копии в сеансе worktree. В worktree с собственным каталогом .claude/skills загружается только эта копия. То же самое применяется к .claude/agents и .claude/commands. Для skills это требует Claude Code версии 2.1.277 или позже.

​

Управляйте worktrees вручную

git worktree add ../project-feature-a -b feature-a

git worktree add ../project-bugfix fix-issue-456

cd ../project-feature-a
claude

git worktree list

git worktree remove ../project-feature-a

​

Не-git системы контроля версий

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

​

Устранение неполадок

​

Claude Code не может войти в worktree при запуске

​

Создание worktree не удаётся на символической ссылке

​

Worktree, созданный Claude Code, содержит исходное содержимое заменённых объектов

​

Файлы Git LFS — это файлы указателей в worktree, который создал Claude Code

• Could not read the repository git config to neutralize filter drivers: Claude Code не мог прочитать .git/config репозитория, например из-за его разрешений. Исправьте это и повторите попытку.
• The repository git config defines a filter driver whose name cannot be neutralized (contains "=" or a newline): переименуйте или удалите этот драйвер фильтра в .git/config и повторите попытку.
• The repository git config has a conditional include (includeIf): переместите параметры, которые includeIf в .git/config вытягивает, непосредственно в этот файл, удалите includeIf и повторите попытку. includeIf в вашей глобальной конфигурации git не вызывает это.
• Git was not run: the repository's own git config sets <key>: сообщение называет ключ, который указывает Git LFS на программу для запуска, такую как lfs.customtransfer.<name>.path или lfs.standalonetransferagent. Если этот параметр ваш, переместите его в вашу глобальную конфигурацию git. Если вы его не узнаёте, удалите его из конфигурации репозитория, так как инструмент или checkout, которому вы не доверяете, мог его написать. Повторите попытку, когда ключ исчезнет из конфигурации репозитория.

​

Создание worktree не удаётся в частичном клоне

​

Can only use --worktree in a git repository

• В папке без системы контроля версий выполните там git init, создайте первый коммит, затем повторите попытку.
• В checkout другой системы контроля версий настройте хук, который предлагает сообщение.
• Чтобы работать непосредственно в каталоге, запустите Claude без --worktree.

​

Каталог worktree belongs to a different repository

​

Claude Code отказывается использовать worktree

• Говорит launch from the parent checkout или Run the resume from the project checkout: вы запустили Claude Code из worktree. Запустите из основной копии вместо этого; worktree не нуждается в пересоздании.
• Говорит it cannot be resumed or re-entered: ничто в этом сеансе не поручается за worktree из того места, где вы запустили. Пересоздайте его; каталог и его работа остаются на диске для ручного восстановления, и когда worktree имеет родительскую копию, возобновление оттуда также работает.
• Говорит it contains the protected checkout: отказанный каталог — это родитель вашей основной копии, такой как ваш домашний каталог. Не удаляйте его. Измените путь worktree, такой как путь, который возвращает ваш hook WorktreeCreate или цель EnterWorktree, чтобы worktree не содержал копию.
• Говорит the protected checkout <path> has a .git entry that could not be examined или has git metadata that could not be resolved: проблема в метаданных git основной копии, а не worktree. Не удаляйте worktree и игнорируйте совет сообщения в конце пересоздать его, который не применяется к этим двум окончаниям. Отремонтируйте основную копию, например проблему разрешений или отказ git dubious ownership на её .git, и повторите попытку. До версии 2.1.302 при использовании git 2.56 или новее окончание could not be resolved также появлялось, когда <path> после the protected checkout содержал посторонний файл .git. Посторонний здесь означает, что путь в строке gitdir: этого файла не ведёт к действительному git-репозиторию. Для восстановления обновите Claude Code и повторите попытку. Если этот путь gitdir: больше не существует, вы также можете удалить файл .git и повторить попытку.
• Говорит its recorded path has a network spelling: Claude Code никогда не возобновляет в worktree по сетевому пути. Пересоздайте worktree по локальному пути.
• Любое другое окончание: сообщение называет проблему и её исправление, такое как удаление перенаправления core.worktree или пересоздание worktree; следуйте ему. Перед удалением каталога, чьё сообщение говорит, что его идентичность git не может быть проверена, сначала решите названную причину, например символическую ссылку в пути worktree или сам git, отказывающийся работать, так как каталог может быть здоров. Когда вы пересоздаёте, сначала спасите любые изменения, которые вам нужны, из старого каталога; он остаётся на диске.

​

Сеанс возобновляется вне его worktree

• Error: cannot resume into worktree <path>: ...This session was not started. для отказа, который таблица показывает как Did not re-enter. Claude Code очищает привязку worktree перед выходом, и ошибка говорит об этом; в следующий раз, когда вы возобновите разговор, сеанс продолжается в текущем каталоге без изоляции worktree. До версии 2.1.260 Claude Code не писал очищенную привязку, поэтому каждая повторная попытка того же возобновления не удалась с той же ошибкой. Если вы подавляете записи стенограммы, очистка не может быть сохранена. Ошибка затем говорит, что та же команда будет отказана снова, и называет --fork-session и запуск нового разговора как способы продолжить без worktree.
• Error: could not verify worktree <path> for this resume, so the resume was aborted... для Could not verify
• Error: ...The worktree binding is kept. для Could not re-enter
• Notice: the worktree <path> for this session no longer exists... для исчезнувшего worktree; Claude Code выводит его и продолжает сеанс, как интерактивное возобновление это делает

​

См. также

• Subagents: делегируйте работу изолированным агентам внутри сеанса
• Cross-session messaging: позвольте сеансам в ваших worktrees передавать результаты друг другу
• Agent teams: координируйте несколько сеансов Claude автоматически
• Manage sessions: назовите, возобновите и переключайтесь между беседами
• Запуск сессии Desktop в собственном worktree: сессии на основе worktree в десктопном приложении