Git worktree в Claude Code: параллельная работа с несколькими сессиями

Практические материалы Ailoot — в документации.

Что такое Git worktree в Claude Code#

Запускать несколько ИИ-сессий в одной папке рискованно: изменения одной сессии могут затереть работу другой. Чем быстрее агенты редактируют код, тем сложнее уследить за всеми одновременными изменениями. Git worktree изолирует рабочие файлы на уровне каталогов.

Команда claude --worktree feature-auth создаёт отдельный каталог .claude/worktrees/feature-auth/ и запускает там Claude Code в своей ветке. Пока изменения не объединены явным образом, одна сессия не меняет файлы другой.

В документации Anthropic объясняется, что отдельный worktree для каждой сессии не позволяет изменениям одной сессии затрагивать файлы другой. Например, в одном терминале можно работать над функцией, а во втором — исправлять ошибку.

Самопроверка: если в коммите уже оказывались файлы с чужими изменениями, отдельные worktree помогут развести параллельную работу.

Чем Git worktree отличается от обычной ветки#

При обычном сценарии ты находишься в ветке main, а затем выполняешь git checkout feature-x. Git обновляет файлы в той же папке. Если в это время работает npm run dev, замена package.json может повлиять на запущенный процесс. Приходится сохранять незакоммиченные изменения через stash, ждать переиндексации IDE, а при возвращении к прежней ветке снова менять рабочие файлы.

С worktree основная папка остаётся на main, а для другой ветки создаётся дополнительный каталог. Например, команда git worktree add ../project-feature-x feature-x создаст ../project-feature-x/ с файлами ветки feature-x. Основной каталог при этом не меняется, и работающий сервер продолжает использовать свои файлы.

До появления удобного режима Claude Code worktree приходилось создавать вручную: выполнить git worktree add, перейти в каталог и запустить claude. Флаг --worktree, также доступный как -w, объединяет эти действия.

Первая параллельная сессия: флаг --worktree#

Открой первый терминал в корневой папке проекта и запусти:

claude --worktree feature-auth

Claude Code выполнит три действия:

1. Создаст .claude/worktrees/feature-auth/ на основе состояния origin/HEAD, обычно соответствующего ветке по умолчанию.
2. Создаст новую ветку worktree-feature-auth.
3. Запустит сессию в созданном каталоге.

Открой второй терминал в корне того же репозитория и выполни:

claude --worktree bugfix-123

Теперь запущены две сессии Claude Code с разными файлами и Git-ветками. Можно, например, поручить первой работу над авторизацией, а второй — исправление падающего теста: каждая сессия работает в отдельном каталоге.

Имя worktree можно не указывать — Claude подберёт его сам:

claude --worktree
# → создаст что-то вроде .claude/worktrees/bright-running-fox/

Пользователям, которые только осваивают Git, стоит добавить .claude/worktrees/ в .gitignore. Иначе команда git status в основном каталоге покажет содержимое worktree как неотслеживаемые файлы:

# .gitignore
.claude/worktrees/

Перед первым вызовом --worktree в новом репозитории открой его обычной командой claude без флага и подтверди доверие к рабочей области. Иначе команда может завершиться ошибкой о неподтверждённом доверии. Это также относится к сочетанию с -p в headless-режиме.

Где хранятся worktree и как их найти#

Стандартный путь для worktree — .claude/worktrees/<value>/ в корне репозитория. Например, для проекта ~/dev/my-app/ worktree с именем feature-auth будет находиться в ~/dev/my-app/.claude/worktrees/feature-auth/.

Если нужно размещать worktree за пределами репозитория, можно настроить hook WorktreeCreate. Дополнительные сведения приведены ниже, в разделе об SVN и Mercurial.

Во время сессии Claude можно попросить перейти в другой существующий worktree, указав его путь, например .claude/worktrees/bugfix-123. Claude вызовет инструмент EnterWorktree. Файлы прежнего каталога останутся нетронутыми; к нему можно вернуться таким же способом.

Список worktree, в который входят основная рабочая копия и созданные вручную каталоги, можно получить стандартной командой Git:

git worktree list

Пример вывода:

/home/user/dev/my-app                  abc1234 [main]
/home/user/dev/my-app/.claude/worktrees/feature-auth  def5678 [worktree-feature-auth]
/home/user/dev/my-app/.claude/worktrees/bugfix-123    9876fed [worktree-bugfix-123]

Копирование .env и секретов: файл .worktreeinclude#

При создании worktree копируются файлы, отслеживаемые Git. Секреты и локальные настройки, исключённые через .gitignore, например .env и .env.local, обычно отсутствуют. Поэтому запуск npm run dev может завершиться ошибкой вроде MISSING DATABASE_URL.

Копировать .env вручную после каждого запуска можно, но легко пропустить этот шаг. Anthropic предлагает хранить в корне проекта файл .worktreeinclude и перечислять в нём игнорируемые Git файлы, которые требуется копировать в новые worktree.

Создай .worktreeinclude в корневом каталоге репозитория и укажи в нём нужные пути:

.env
.env.local
config/secrets.json

Поддерживаются шаблоны, совместимые с .gitignore:

.env*
*.local
config/*.json
.vscode/settings.json

В документации Anthropic уточняется: файл использует синтаксис gitignore, копируются только совпавшие файлы, уже исключённые из Git, а отслеживаемые Git файлы повторно не копируются.

Например, package.json не будет скопирован по шаблону из .worktreeinclude, если он не указан в .gitignore. Один файл .worktreeinclude применяется при создании worktree командой --worktree, для worktree субагентов и в сессиях настольного приложения Claude.

Создание worktree из pull request для код-ревью#

При стандартном код-ревью нужно изучить PR, запустить тесты и, возможно, оставить замечания. Если переключить основную рабочую копию командой вроде git checkout pull/1234/head, изменится каталог, в котором могут идти другие процессы.

Создать отдельный worktree для PR можно одной командой:

claude --worktree "#1234"

Claude Code получает ветку PR, создаёт worktree .claude/worktrees/pr-1234/ и запускает сессию в нём. После этого можно попросить изучить diff, выполнить тесты и проверить логику изменений, пока основная рабочая копия продолжает использовать свою ветку.

Можно также передать полный URL pull request:

claude --worktree https://github.com/OWNER/REPO/pull/1234

Базовая ветка: worktree.baseRef со значениями fresh или head#

Стандартное значение означает, что новый worktree начинается от origin/HEAD. Такой каталог соответствует последнему синхронизированному состоянию удалённой ветки. При этом локальные коммиты, которых ещё нет в remote, и незакоммиченные изменения текущей ветки в него не переходят.

Чтобы создать worktree от текущего локального коммита HEAD, добавь следующий блок в .claude/settings.json или глобальные настройки:

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

После настройки claude --worktree experimental-feature начинается от текущего локального HEAD. Это полезно, если функция уже содержит локальные коммиты, ещё не отправленные в remote. Незакоммиченные правки отслеживаемых файлов не переносятся. Если они нужны субагенту, явно сохрани и перенеси требуемые изменения и проверь diff получателя. Не путай это с .worktreeinclude, который работает с игнорируемыми локальными файлами.

Параметр принимает строго два значения: "fresh" для origin/HEAD и "head" для локального HEAD. Указать произвольную ветку вроде "feature-branch" или хеш коммита нельзя.

Автоматическая изоляция субагентов: isolation: worktree#

Если поручить Claude сразу несколько задач — например, изучить базу, проверить API и исследовать тесты, — субагенты по умолчанию могут использовать одну рабочую копию. Одновременная запись в общий файл способна привести к конфликтам. Worktree позволяет дать каждому агенту собственное рабочее пространство.

Первый способ — попросить об этом прямо в чате:

Используй worktrees для своих агентов.

Claude будет применять изоляцию worktree к последующим субагентам текущей сессии.

Второй вариант — указать настройку в файле субагента, например .claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Изучает diff и составляет замечания по коду
isolation: worktree
---

Проверь изменения, изучи diff и найди возможные логические ошибки...

Каждому запуску этого субагента будет выделен временный worktree в .claude/worktrees/. Если агент не оставил изменений, каталог удаляется после завершения. При наличии незакоммиченных изменений Claude спросит, сохранить worktree или удалить его.

Базовая ветка для worktree субагента определяется так же, как для --worktree: по умолчанию используется origin/HEAD, а при worktree.baseRef: head — локальный HEAD.

Как выбрать между worktree, /bg, subagent и Agent View#

Типовые сочетания:

• «Две функции одновременно вручную» — открой два терминала и запусти в каждом claude --worktree с отдельным именем.
• «Запусти долгий рефакторинг в фоне» — используй /bg вместе с /goal, задав условие завершения. Сессия продолжит работу отдельно от текущего окна.
• «Проведи три исследования по одному запросу» — запусти три субагента с isolation: worktree, чтобы каждому достался свой каталог.
• «Посмотри, какие задачи выполняются» — открой claude agents, чтобы просмотреть сессии и отфильтровать их по состоянию running, blocked или done.

Пять распространённых проблем с worktree#

1. В новом worktree нет .env, поэтому проект не запускается. Worktree создаётся как свежая копия, а исключённые Git файлы в неё не включаются автоматически. Добавь в .worktreeinclude шаблон .env* и другие необходимые локальные конфиги. Файл должен лежать в корне репозитория, а не в .claude/.

2. Вернулся в основной каталог и решил, что изменения worktree пропали. Корневой каталог и worktree — две разные рабочие копии. Если перейти обратно через cd, изменения в worktree останутся на месте. Но команды Git выполняются в текущем каталоге: если ошибочно запустить git stash в основной папке, изменения сохранятся из основной ветки, а не из worktree.

3. Запустил пять сессий и забыл, какая чем занята. Anthropic предупреждает, что большинству разработчиков трудно одновременно удерживать в фокусе больше двух-трёх сессий. Если в Agent View уже неясно, за что отвечает каждая из них, сократи число параллельных задач. Когда требуется координировать больше агентов, рассмотри /goal и субагентов вместо ручного запуска каждой сессии.

4. Worktree, созданные через -p в headless-режиме, не удаляются автоматически. Например, команда claude --worktree feature-x -p "do thing" завершится без интерактивного запроса о сохранении или удалении. Поэтому каталог останется на диске. Удалить его можно вручную: git worktree remove .claude/worktrees/feature-x. Также можно настроить скрипт по расписанию, который удаляет каталоги старше семи дней.

5. Не подтверждено доверие к новой папке. Если это первое открытие репозитория, команда claude --worktree может завершиться ошибкой. Сначала запусти claude без флагов, подтверди доверие к рабочей области и выйди из сессии. После этого можно использовать --worktree. Подтверждение нужно, чтобы Claude не получал доступ к новому проекту без согласия пользователя.

Очистка: какие каталоги удаляются автоматически#

Порядок автоматической очистки зависит от изменений внутри worktree и способа запуска сессии. Документация Anthropic описывает такие случаи: если в каталоге нет незакоммиченных изменений, неотслеживаемых файлов и новых коммитов, worktree и его ветка удаляются при выходе. Если сессия имеет имя, Claude может вместо этого спросить, нужно ли сохранить каталог для дальнейшей работы.

Сценарий 1: ты создал worktree, ничего в нём не изменил и завершил сессию — каталог удаляется.

Сценарий 2: в worktree есть незакоммиченные изменения — при выходе Claude спросит, сохранить или удалить его. Вариант «Keep» оставляет каталог и ветку. Вариант «Remove» удаляет папку вместе с незакоммиченными изменениями и новыми коммитами. Перед удалением проверь, что важные изменения сохранены.

Сценарий 3: команда запущена с -p в headless-режиме и завершилась — worktree может остаться на диске. Удали его вручную:

git worktree remove .claude/worktrees/feature-x

Worktree субагентов и сессий /bg могут удаляться фоновой очисткой, если они старше cleanupPeriodDays и не содержат несохранённой работы. Параметр задаётся в настройках; обычно его значение по умолчанию составляет 30 дней. Worktree, созданные через --worktree, автоматическая очистка не затрагивает — следи за ними самостоятельно.

Поддержка SVN, Perforce и Mercurial через WorktreeCreate#

Флаг --worktree изначально рассчитан на Git и не создаёт рабочую копию для SVN или Mercurial напрямую. В Claude Code предусмотрены hooks WorktreeCreate, создающий изолированный каталог, и WorktreeRemove, удаляющий его.

Ниже приведён пример hook для SVN из документации Anthropic:

{
  "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\"'"
          }
        ]
      }
    ]
  }
}

Hook получает имя worktree из stdin, например { "name": "feature-auth" }, выполняет svn checkout в подготовленный каталог и печатает путь в stdout. Claude Code использует этот путь как рабочую папку новой сессии.

При использовании собственного hook .worktreeinclude не обрабатывается. Если новой рабочей копии требуются .env или другие файлы, исключённые Git, добавь их копирование в скрипт hook.

Другие инструменты для параллельной работы#

Worktree изолирует файлы, /bg запускает задачу в фоне, а субагент получает отдельное поручение. Вместе эти механизмы помогают выполнять несколько задач параллельно, сохраняя отдельные рабочие каталоги и контексты.

Открыть Ailoot.