**Главное**
Git worktree — отдельный рабочий каталог для другой ветки того же репозитория. Команда `claude --worktree ` создаёт каталог `.claude/worktrees//` и запускает в нём Claude Code. Можно открыть два терминала и работать в двух независимых сессиях, поскольку каждая использует свои файлы. Эта возможность доступна в Claude Code v2.0 и новее. Для настройки копирования локальных файлов служит `.worktreeinclude`, а базовую ветку можно выбрать параметром `worktree.baseRef`.
Запускать несколько ИИ-сессий в одной папке рискованно: изменения одной сессии могут затереть работу другой. Чем быстрее агенты редактируют код, тем сложнее уследить за всеми одновременными изменениями. Git worktree изолирует рабочие файлы на уровне каталогов.
Команда `claude --worktree feature-auth` создаёт отдельный каталог `.claude/worktrees/feature-auth/` и запускает там Claude Code в своей ветке. Пока изменения не объединены явным образом, одна сессия не меняет файлы другой.
В документации Anthropic объясняется, что отдельный worktree для каждой сессии не позволяет изменениям одной сессии затрагивать файлы другой. Например, в одном терминале можно работать над функцией, а во втором — исправлять ошибку.
Самопроверка: если в коммите уже оказывались файлы с чужими изменениями, отдельные worktree помогут развести параллельную работу.
## Чем Git worktree отличается от обычной ветки
**Главное**
`git checkout` переключает ветку в текущей папке, поэтому набор файлов на диске заменяется. `git worktree add` создаёт для другой ветки ещё одну папку. Обе рабочие копии доступны одновременно, а перейти между ними можно командой `cd`. История Git и удалённый репозиторий у них общие.
При обычном сценарии ты находишься в ветке `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`. Основной каталог при этом не меняется, и работающий сервер продолжает использовать свои файлы.
| Параметр | Ветка через `git checkout` | Каталог через `git worktree add` |
|----|----|----|
| Файлы рабочей копии | Заменяются при переключении | Размещаются в отдельной папке |
| Одновременная работа в двух ветках | Нет | Да |
| Незакоммиченные изменения | Часто нужно сохранять через `git stash` | Остаются в своей рабочей копии |
| Переход между ветками | Git обновляет файлы | Достаточно выполнить `cd` |
| Использование диска | Одна копия файлов | Несколько копий — по одной на каждую ветку |
До появления удобного режима Claude Code worktree приходилось создавать вручную: выполнить `git worktree add`, перейти в каталог и запустить `claude`. Флаг `--worktree`, также доступный как `-w`, объединяет эти действия.
## Первая параллельная сессия: флаг `--worktree`
**Главное**
Команда `claude --worktree feature-auth` создаёт каталог `.claude/worktrees/feature-auth/`, формирует ветку `worktree-feature-auth` от `origin/HEAD` и запускает Claude Code в новом каталоге. Вторую независимую сессию можно открыть в другом терминале, указав другое имя. Если имя не задано — `claude --worktree` — Claude сгенерирует его автоматически, например `bright-running-fox`.
Открой первый терминал в корневой папке проекта и запусти:
```bash
claude --worktree feature-auth
```
Claude Code выполнит три действия:
1. Создаст `.claude/worktrees/feature-auth/` на основе состояния `origin/HEAD`, обычно соответствующего ветке по умолчанию.
2. Создаст новую ветку `worktree-feature-auth`.
3. Запустит сессию в созданном каталоге.
Открой второй терминал в корне того же репозитория и выполни:
```bash
claude --worktree bugfix-123
```
Теперь запущены две сессии Claude Code с разными файлами и Git-ветками. Можно, например, поручить первой работу над авторизацией, а второй — исправление падающего теста: каждая сессия работает в отдельном каталоге.
Имя worktree можно не указывать — Claude подберёт его сам:
```bash
claude --worktree
# → создаст что-то вроде .claude/worktrees/bright-running-fox/
```
Пользователям, которые только осваивают Git, стоит добавить `.claude/worktrees/` в `.gitignore`. Иначе команда `git status` в основном каталоге покажет содержимое worktree как неотслеживаемые файлы:
```gitignore
# .gitignore
.claude/worktrees/
```
Перед первым вызовом `--worktree` в новом репозитории открой его обычной командой `claude` без флага и подтверди доверие к рабочей области. Иначе команда может завершиться ошибкой о неподтверждённом доверии. Это также относится к сочетанию с `-p` в headless-режиме.
## Где хранятся worktree и как их найти
/` в корне репозитория. Например, для проекта `~/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:
```bash
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 — это свежая рабочая копия. Файлы из `.gitignore`, включая `.env`, `.env.local` и локальные настройки, туда сами по себе не попадают. Файл `.worktreeinclude` в корне проекта задаёт шаблоны в синтаксисе `.gitignore` для автоматического копирования таких файлов в каждый новый worktree. Механизм действует при использовании `--worktree`, worktree субагентов и сессий в настольном приложении Claude.
При создании 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 для код-ревью
**Главное**
Команда `claude --worktree "#1234"` получает pull request `#1234` из `origin` и создаёт каталог `.claude/worktrees/pr-1234/` с его веткой. Вместо номера можно указать URL PR, например `claude --worktree https://github.com/OWNER/REPO/pull/1234`. Такой отдельный каталог позволяет изучить изменения и запустить тесты, не затрагивая основную рабочую копию.
При стандартном код-ревью нужно изучить PR, запустить тесты и, возможно, оставить замечания. Если переключить основную рабочую копию командой вроде `git checkout pull/1234/head`, изменится каталог, в котором могут идти другие процессы.
Создать отдельный worktree для PR можно одной командой:
```bash
claude --worktree "#1234"
```
Claude Code получает ветку PR, создаёт worktree `.claude/worktrees/pr-1234/` и запускает сессию в нём. После этого можно попросить изучить diff, выполнить тесты и проверить логику изменений, пока основная рабочая копия продолжает использовать свою ветку.
Можно также передать полный URL pull request:
```bash
claude --worktree https://github.com/OWNER/REPO/pull/1234
```
## Базовая ветка: `worktree.baseRef` со значениями `fresh` или `head`
**Главное**
По умолчанию worktree создаётся от `origin/HEAD`, то есть от актуального состояния удалённой ветки по умолчанию. Чтобы включить локальные неопубликованные коммиты, задай `worktree.baseRef: "head"`. HEAD обозначает коммит: незакоммиченные изменения отслеживаемых файлов остаются в исходной копии и требуют отдельного явного переноса. Допускаются только значения `fresh` и `head`; произвольные ссылки на ветки не поддерживаются.
Стандартное значение означает, что новый worktree начинается от `origin/HEAD`. Такой каталог соответствует последнему синхронизированному состоянию удалённой ветки. При этом локальные коммиты, которых ещё нет в remote, и незакоммиченные изменения текущей ветки в него не переходят.
Чтобы создать worktree от текущего локального коммита HEAD, добавь следующий блок в `.claude/settings.json` или глобальные настройки:
```json
{
"worktree": {
"baseRef": "head"
}
}
```
После настройки `claude --worktree experimental-feature` начинается от текущего локального `HEAD`. Это полезно, если функция уже содержит локальные коммиты, ещё не отправленные в remote. Незакоммиченные правки отслеживаемых файлов не переносятся. Если они нужны субагенту, явно сохрани и перенеси требуемые изменения и проверь diff получателя. Не путай это с `.worktreeinclude`, который работает с игнорируемыми локальными файлами.
Параметр принимает строго два значения: `"fresh"` для `origin/HEAD` и `"head"` для локального `HEAD`. Указать произвольную ветку вроде `"feature-branch"` или хеш коммита нельзя.
## Автоматическая изоляция субагентов: `isolation: worktree`
**Главное**
Субагент Claude Code предназначен для отдельной задачи, например код-ревью, рефакторинга или поиска информации. Без настройки параллельные субагенты по умолчанию могут работать в одной папке и затрагивать одни и те же файлы. Параметр `isolation: worktree` во frontmatter субагента выделяет ему временный worktree. Если изменений, которые нужно сохранить, нет, каталог удаляется по завершении.
Если поручить Claude сразу несколько задач — например, изучить базу, проверить API и исследовать тесты, — субагенты по умолчанию могут использовать одну рабочую копию. Одновременная запись в общий файл способна привести к конфликтам. Worktree позволяет дать каждому агенту собственное рабочее пространство.
Первый способ — попросить об этом прямо в чате:
```
Используй worktrees для своих агентов.
```
Claude будет применять изоляцию worktree к последующим субагентам текущей сессии.
Второй вариант — указать настройку в файле субагента, например `.claude/agents/code-reviewer.md`:
```yaml
---
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 Code решают разные задачи. Worktree разделяет файлы между сессиями. `/bg` запускает работу в фоне. Subagent получает отдельную специализацию, инструкции и набор инструментов. Agent View показывает сессии в интерфейсе. Их можно сочетать: `/bg` может создавать worktree, субагент с `isolation: worktree` получает временный каталог, а Agent View показывает сессии в общем списке.
| Инструмент | Что обеспечивает | Когда использовать |
|----|----|----|
| `claude --worktree ` | Отдельные файлы и ветку в собственной папке | Нужно вручную держать несколько сессий в разных терминалах |
| `/bg` или `Ctrl+B` | Выполнение задачи в фоне | Задача долгая и не должна блокировать текущее окно; worktree может создаваться автоматически |
| Subagent с `isolation: worktree` | Отдельную рабочую папку внутри сессии | Одна задача распределяется между несколькими агентами, и нужно избежать перезаписи файлов |
| `claude agents` (Agent View) | Интерфейс для просмотра сессий | Нужно видеть запущенные, приостановленные и завершённые сессии в одном месте |
| `/goal` | Выполнение задачи до заданного условия | Нужно, чтобы Claude продолжал работу без промтов между отдельными ходами |
Типовые сочетания:
- **«Две функции одновременно вручную»** — открой два терминала и запусти в каждом `claude --worktree` с отдельным именем.
- **«Запусти долгий рефакторинг в фоне»** — используй `/bg` вместе с `/goal`, задав условие завершения. Сессия продолжит работу отдельно от текущего окна.
- **«Проведи три исследования по одному запросу»** — запусти три субагента с `isolation: worktree`, чтобы каждому достался свой каталог.
- **«Посмотри, какие задачи выполняются»** — открой `claude agents`, чтобы просмотреть сессии и отфильтровать их по состоянию `running`, `blocked` или `done`.
## Пять распространённых проблем с worktree
**Главное**
Проверь, что в `.worktreeinclude` перечислены необходимые локальные файлы; помни, что worktree — отдельная рабочая копия; следи за количеством одновременных сессий; настрой очистку временных каталогов через `cleanupPeriodDays`; перед первым запуском подтверди доверие к репозиторию. Эти шаги помогают избежать отсутствующих настроек, путаницы с файлами и ошибок запуска.
**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, созданный через `--worktree`, удаляется при выходе; при наличии изменений Claude задаёт вопрос. Каталоги субагентов и фоновых сессий удаляются по истечении `cleanupPeriodDays`, если в них нет незавершённой работы. Для worktree, созданного с `-p`, может потребоваться ручная очистка через `git worktree remove`.
Порядок автоматической очистки зависит от изменений внутри worktree и способа запуска сессии. Документация Anthropic описывает такие случаи: если в каталоге нет незакоммиченных изменений, неотслеживаемых файлов и новых коммитов, worktree и его ветка удаляются при выходе. Если сессия имеет имя, Claude может вместо этого спросить, нужно ли сохранить каталог для дальнейшей работы.
**Сценарий 1:** ты создал worktree, ничего в нём не изменил и завершил сессию — каталог удаляется.
**Сценарий 2:** в worktree есть незакоммиченные изменения — при выходе Claude спросит, сохранить или удалить его. Вариант «Keep» оставляет каталог и ветку. Вариант «Remove» удаляет папку вместе с незакоммиченными изменениями и новыми коммитами. Перед удалением проверь, что важные изменения сохранены.
**Сценарий 3:** команда запущена с `-p` в headless-режиме и завершилась — worktree может остаться на диске. Удали его вручную:
```bash
git worktree remove .claude/worktrees/feature-x
```
Worktree субагентов и сессий `/bg` могут удаляться фоновой очисткой, если они старше `cleanupPeriodDays` и не содержат несохранённой работы. Параметр задаётся в настройках; обычно его значение по умолчанию составляет 30 дней. Worktree, созданные через `--worktree`, автоматическая очистка не затрагивает — следи за ними самостоятельно.
## Поддержка SVN, Perforce и Mercurial через `WorktreeCreate`
**Главное**
По умолчанию режим worktree использует `git worktree`. Для SVN, Perforce, Mercurial и других систем контроля версий можно настроить hooks `WorktreeCreate` и `WorktreeRemove` в параметрах Claude Code. Hook получает имя через stdin, выводит путь к созданному каталогу и завершает работу с кодом 0. При использовании собственного hook файл `.worktreeinclude` не применяется — копирование локальных файлов нужно реализовать самостоятельно.
Флаг `--worktree` изначально рассчитан на Git и не создаёт рабочую копию для SVN или Mercurial напрямую. В Claude Code предусмотрены hooks `WorktreeCreate`, создающий изолированный каталог, и `WorktreeRemove`, удаляющий его.
Ниже приведён пример hook для SVN из документации Anthropic:
```json
{
"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` позволяет выполнять задачу в фоне, subagent выделяет отдельную задачу и набор инструментов, а `/goal` помогает продолжать работу до выполнения условия. Каждый механизм решает свою задачу; их можно сочетать для координации нескольких параллельных процессов.
Worktree изолирует файлы, `/bg` запускает задачу в фоне, а субагент получает отдельное поручение. Вместе эти механизмы помогают выполнять несколько задач параллельно, сохраняя отдельные рабочие каталоги и контексты.
### Официальные источники
- [Параллельные сессии с worktree — документация Claude Code](https://code.claude.com/docs/en/worktrees)
- [Создание собственных субагентов — документация Claude Code](https://code.claude.com/docs/en/sub-agents)
- [Журнал изменений Claude Code](https://code.claude.com/docs/en/changelog)
- [Запуск агентов параллельно — документация Claude Code](https://code.claude.com/docs/en/agents)
- [Agent View — документация Claude Code](https://code.claude.com/docs/en/agent-view)
- [Справочная страница команды `git worktree`](https://git-scm.com/docs/git-worktree)
[Открыть Ailoot](https://ailoot.ai/).
## Вопросы и ответы
### Переносит ли baseRef head незакоммиченные правки в worktree?
Нет. Он начинает от локального коммита HEAD, включая ещё не отправленные коммиты. Незакоммиченные правки отслеживаемых файлов остаются в исходной копии. Нужный WIP перенеси явно и проверь новый worktree.
### Почему в новом worktree отсутствует .env?
Свежая рабочая копия не содержит игнорируемые Git локальные файлы. В Claude Code .worktreeinclude перечисляет копируемые игнорируемые файлы; пользовательский WorktreeCreate hook должен копировать их самостоятельно. Включай только необходимое задаче.
## Ailoot · Компания и портфель её проектов
Ailoot опирается на накопленный опыт работы, большую клиентскую базу, стабильный сервис и постоянный контроль KPI.
Компания и портфель её проектов: миллионы клиентов; продажи на миллиарды ежемесячно.
Этот опыт Ailoot использует для API-доступа к нейросетям в продуктах клиентов, агентах, приложениях и автоматизациях.