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

​

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

claude --worktree feature-auth

​

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

​

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

​

Очистка worktrees

• Worktree чист: для безымянного сеанса Claude автоматически удаляет worktree и его ветку. Именованный сеанс сначала предлагает вам, чтобы вы могли сохранить worktree на потом
• Worktree содержит работу: Claude предлагает вам сохранить или удалить worktree. Сохранение сохраняет каталог и ветку, чтобы вы могли вернуться позже. Удаление удаляет каталог worktree и его ветку, вместе со всей работой в них
• Состояние worktree не может быть проверено: когда Claude Code не может подсчитать изменения worktree или не может проверить проверки его подмодулей, он предлагает вам вместо автоматического удаления worktree. Подсказка указывает, что он не смог проверить

​

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

• Каталог запуска: возобновите из основной копии или другого каталога репозитория. 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

​

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

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

{
  "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 файлы в worktrees

.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 hook

​

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

• Каталог .git репозитория: команды git в worktree записывают в общий каталог .git основного репозитория, и sandboxing позволяет эти записи, поэтому команды, такие как git commit, работают из worktree с включённой песочницей.
• Плагины: плагины, установленные в области проекта из основной копии, также загружаются в worktrees того же репозитория, поэтому вам не нужно переустанавливать их для каждого worktree. Требуется Claude Code версии 2.1.200 или позже.
• Одобрения разрешений: выбор “Да, и больше не спрашивать” для команды Bash в сеансе worktree сохраняет правило в .claude/settings.local.json основной копии, поэтому оно применяется в основной копии и в каждом другом worktree репозитория, и оно выживает удаление worktree. На Windows и в других случаях, когда Claude Code не использует корень репозитория, правило остаётся с этим worktree. До версии 2.1.211 одобрение, предоставленное в worktree, было сохранено внутри этого worktree, не применялось в другом месте и было потеряно при удалении 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 не удаётся на символической ссылке

​

Файлы 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, которому вы не доверяете, мог его написать. Повторите попытку, когда ключ исчезнет из конфигурации репозитория.

​

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, и повторите попытку.
• Говорит 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 parallel sessions: сеансы на основе worktree в десктопном приложении