# Как запустить несколько агентов Claude Code одновременно в одном проекте: git worktree и изолированные workspace

> AI Release · @ai_release1 · https://ai-release.org/guides/kak-zapustit-neskolko-agentov-claude-code-odnovremenno.html

## TL;DR

- Время выполнения: 25–30 минут
- Уровень сложности: Intermediate
- Понадобится: Git с поддержкой `git worktree` (проверяется командой `git worktree --help`; если выдаёт `git: 'worktree' is not a git command` — обновите Git до версии из документации вашего дистрибутива), Claude Code CLI (`claude --version`), терминал, `tmux` или несколько окон терминала, Node.js/npm — если проект на JavaScript
- Результат: N независимых рабочих каталогов на одну историю Git, в каждом — свой агент, своя ветка и свой порт дев-сервера

Три главных ограничения, о которых обычно молчат гайды: worktree **не позволяет** двум агентам работать на одной ветке, `node_modules` **не копируется** в новый worktree, а git-хуки **общие** для всех worktree (живут в одном `.git/hooks`). Всё остальное изолируется.

## Требования и подготовка
![Иллюстрация к разделу «Требования и подготовка»](https://ai-release.org/guides/img/kak-zapustit-neskolko-agentov-claude-code-odnovremenno-ru-1.jpg?v=1795250640)


- ОС: Linux, macOS или Windows (в Windows все команды ниже выполняются в PowerShell, кроме `sed` — для него дан отдельный вариант)
- Git — проверьте `git worktree --help`; команда должна вывести справку, а не ошибку
- Claude Code CLI — проверьте `claude --version`
- `tmux` (Linux/macOS) для параллельных сессий: `tmux -V`; на Windows проще открыть несколько окон PowerShell
- Свободное место: worktree не дублирует `.git` из истории, но каждый каталог получит свою копию `node_modules` (для типового фронтенд-проекта это сотни мегабайт)
- Права на запись в родительский каталог проекта — worktree создаются рядом с основным репозиторием

**Пример:** проект лежит в `/home/user/projects/myapp`. Агентские каталоги создадим рядом: `/home/user/projects/myapp-agent-1` и `/home/user/projects/myapp-agent-2`.

**Что такое worktree.** `git worktree` — механизм Git, который позволяет держать несколько рабочих каталогов (working tree), привязанных к **одному** репозиторию `.git`. В каждом каталоге — своя ветка, свой индекс и свои незакоммиченные файлы, но история коммитов общая. Это дешевле, чем `git clone`, потому что объекты репозитория не копируются.

Схема раскладки:

```
/home/user/projects/myapp/ ← основной worktree, ветка main, общий .git
├── .git/ ← один репозиторий на всех
├── .gitignore
├── CLAUDE.md
└── src/
/home/user/projects/myapp-agent-1/ ← агент 1, ветка agent/1-auth
/home/user/projects/myapp-agent-2/ ← агент 2, ветка agent/2-api
/home/user/projects/myapp-review/ ← агент-ревьюер, detached HEAD, только чтение
```

**Что сделать:** приведите основной каталог в чистое состояние и зафиксируйте игнорируемые артефакты.

```bash
cd /home/user/projects/myapp
git status
git checkout main
git pull --ff-only
git status --porcelain
```

**Зачем:** worktree создаётся от коммита. Если в `main` висят незакоммиченные правки, новый каталог их не получит — агент будет работать от другой базы, и вы получите расхождение, которое трудно заметить.

**Как проверить:** `git status` печатает `On branch main` и `nothing to commit, working tree clean`; `git status --porcelain` не печатает ничего (пустой вывод = чисто). `git worktree list` покажет ровно одну строку:

```
/home/user/projects/myapp a1b2c3d [main]
```

Добавьте в `.gitignore` локальные артефакты, чтобы они не приехали в чужие ветки при мердже:

```bash
printf '\nnode_modules/\n.env\n.next/\ndist/\n' >> .gitignore
git add .gitignore && git commit -m "chore: ignore local artifacts"
```

**Почему это работает:** игнорируемые файлы физически лежат в каталоге worktree, но не попадают в индекс — значит, агент 1 не сможет случайно закоммитить `.env` агента 2.

Отдельно проверьте хуки: `git config --get core.hooksPath` (пустой вывод = стандартный `.git/hooks`). Хук, который делает `npm ci` или линт, сработает **во всех** worktree сразу — это единственная общая точка, которую нельзя развести по каталогам. Если такой хук мешает параллельной работе, отключите его на время эксперимента (`git config core.hooksPath /dev/null`) и верните обратно.

Если проект уже использует субагентов и общие правила в `CLAUDE.md`, посмотрите [как настроить субагентов и общий ИИ-суперагент](https://ai-release.org/guides/claude-code-dlya-komandy-kak-nastroit-subagentov-i-obsc.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide) — эти настройки применяются в каждом worktree отдельно.

## Шаг 1. Создайте worktree под каждого агента

**Что сделать:** создайте по каталогу на агента, каждому — своя ветка.

```bash
cd /home/user/projects/myapp
git worktree add ../myapp-agent-1 -b agent/1-auth
git worktree add ../myapp-agent-2 -b agent/2-api
```

**Зачем:** `-b <имя>` создаёт новую ветку от текущего HEAD (`main`) и сразу переключает на неё новый каталог. Агенты перестают делить один индекс: коммит одного не меняет состояние другого.

**Как проверить:** команда печатает примерно это:

```
Preparing worktree (new branch 'agent/1-auth')
HEAD is now at a1b2c3d chore: ignore local artifacts
```

Затем `git worktree list`:

```
/home/user/projects/myapp a1b2c3d [main]
/home/user/projects/myapp-agent-1 a1b2c3d [agent/1-auth]
/home/user/projects/myapp-agent-2 a1b2c3d [agent/2-api]
```

Если нужен агент-ревьюер, который только читает код и ничего не пушит, создайте worktree в detached-состоянии (HEAD не привязан к ветке):

```bash
git worktree add --detach ../myapp-review origin/main
```

Теперь выдайте каждому агенту свой порт и свои зависимости:

```bash
cd ../myapp-agent-1
cp ../myapp/.env .env
sed -i 's/^PORT=.*/PORT=3001/' .env
npm ci
```

Вариант для Windows PowerShell:

```powershell
Set-Location ..\myapp-agent-1
Copy-Item ..\myapp\.env .env
(Get-Content .env) -replace '^PORT=.*','PORT=3001' | Set-Content .env
npm ci
```

**Почему это работает:** `node_modules` не отслеживается Git и в новый каталог не попадает — `npm ci` ставит зависимости заново из lock-файла, поэтому версии пакетов совпадают во всех worktree.

Распределение ресурсов держите в одной таблице, чтобы не путаться:

| Агент | Каталог | Ветка | PORT |
|---|---|---|---|
| 1 | `/home/user/projects/myapp-agent-1` | `agent/1-auth` | 3001 |
| 2 | `/home/user/projects/myapp-agent-2` | `agent/2-api` | 3002 |
| review | `/home/user/projects/myapp-review` | detached (`origin/main`) | не нужен |

## Шаг 2. Запустите агентов параллельно
![Иллюстрация к разделу «Шаг 2. Запустите агентов параллельно»](https://ai-release.org/guides/img/kak-zapustit-neskolko-agentov-claude-code-odnovremenno-ru-2.jpg?v=1795250645)


**Что сделать:** откройте отдельную терминальную сессию на каждый каталог и запустите в каждой `claude`.

```bash
tmux new -s agent1 -c /home/user/projects/myapp-agent-1
# внутри сессии:
claude
```

Вторая сессия — в отдельном окне терминала:

```bash
tmux new -s agent2 -c /home/user/projects/myapp-agent-2
claude
```

**Зачем:** `claude` запускается в текущем каталоге и читает локальные файлы проекта и конфиг `.claude/settings.json` из этого каталога. Разные каталоги = разные рабочие копии, агенты не перезаписывают файлы друг друга.

**Как проверить:** `tmux ls` печатает список активных сессий:

```
agent1: 1 windows (created Tue Jan 14 11:02:15 2025)
agent2: 1 windows (created Tue Jan 14 11:02:40 2025)
```

Внутри каждой сессии `pwd` показывает её собственный каталог.

**Пример постановки задачи агенту 1** (в его сессии, каталог `myapp-agent-1`):

```
Реализуй форму логина в src/auth/. Работай только в этом каталоге,
ветка agent/1-auth. Запусти npm test перед коммитом.
```

Агенту 2 в это же время:

```
Добавь эндпоинт GET /api/health в src/api/. Ветка agent/2-api.
Порт дев-сервера 3002, не занимай 3001.
```

Полезные команды `tmux`: `Ctrl+b`, затем `d` — отсоединиться, не убивая агента; `tmux attach -t agent1` — вернуться в сессию. Если `tmux` недоступен, откройте два окна терминала вручную — результат тот же.

Точный набор флагов и режимов запуска CLI (`--continue`, `--resume`, `--add-dir` и другие) зависит от вашей версии — **сверьтесь с `claude --help` и документацией**, а не с чужими скриншотами. Если планируете между несколькими ролями (архитектор, тестировщик, ревьюер), схема разделения описана в гайде [Claude Code Agent Teams: команда агентов от задачи до релиза](https://ai-release.org/guides/claude-code-agent-teams-komanda-agentov.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).

## Шаг 3. Проверьте изоляцию и сведите результат
![Иллюстрация к разделу «Шаг 3. Проверьте изоляцию и сведите результат»](https://ai-release.org/guides/img/kak-zapustit-neskolko-agentov-claude-code-odnovremenno-ru-3.jpg?v=1795250652)


**Что сделать:** убедитесь, что ветки разошлись, тесты зелёные в каждой, и только потом мерджите.

```bash
git worktree list
git -C ../myapp-agent-1 status -sb
git -C ../myapp-agent-1 log --oneline -3
```

**Зачем:** `status -sb` показывает первую строку вида `## agent/1-auth` — это доказательство, что агент 1 коммитит в свою ветку, а не в `main`. `log` показывает, что коммиты появились именно там.

**Как проверить:** ожидаемый вывод:

```
## agent/1-auth
 M src/auth/login.tsx
```

и далее список коммитов агента. Если вместо `## agent/1-auth` вы видите `## main` — агент работает не в том каталоге, остановите его и проверьте `pwd`.

Прогоните тесты в каждом worktree по отдельности:

```bash
cd /home/user/projects/myapp-agent-1 && npm test
cd /home/user/projects/myapp-agent-2 && npm test
```

Ожидаемо: оба запуска зелёные. Если тесты падают только **после** мерджа, значит ветки конфликтуют по смыслу, а не по строкам — это нормальный сигнал разбирать изменения вручную.

Сведение результата:

```bash
cd /home/user/projects/myapp
git checkout main
git merge --no-ff agent/1-auth -m "merge: agent 1 auth"
git merge --no-ff agent/2-api -m "merge: agent 2 api"
git worktree remove ../myapp-agent-1
git worktree remove ../myapp-agent-2
git branch -d agent/1-auth agent/2-api
```

`--no-ff` сохраняет отдельный merge-коммит, по которому видно, какой агент что принёс.

**Чек-лист приёмки:**

- [ ] `git worktree list` показывает `main` + по строке на каждый агентский каталог
- [ ] в каждом worktree `git status -sb` начинается с `## agent/...`
- [ ] у каждого агента свой `PORT` в локальном `.env`, дев-серверы не конфликтуют
- [ ] `npm test` зелёный в каждом worktree **до** мерджа
- [ ] `git worktree remove` и `git branch -d` прошли без ошибок, `git worktree list` снова показывает одну строку

## Возможные проблемы и решения

**Проблема. Второй агент не создаётся на той же ветке**

- Ошибка: `fatal: 'agent/1-auth' is already checked out at '/home/user/projects/myapp-agent-1'`
- Причина: Git запрещает держать одну ветку в двух worktree одновременно — иначе два индекса писали бы в одну ссылку `refs/heads/...`.
- Решение: дайте агенту собственную ветку или detached-каталог для чтения:

```bash
git worktree add ../myapp-agent-3 -b agent/3-ui
# либо только для ревью, без ветки:
git worktree add --detach ../myapp-review-2 origin/main
```

Проверка: `git worktree list` — у каждого каталога своя ветка или `detached`.

**Проблема. Дев-серверы двух агентов дерутся за порт**

- Ошибка: `Error: listen EADDRINUSE: address already in use :::3000`
- Причина: оба worktree скопировали `.env` из основного каталога с одинаковым `PORT=3000`.
- Решение: правьте `.env` **в каждом** каталоге отдельно, файл в `.gitignore` и не мерджится:

```bash
cd ../myapp-agent-2 && sed -i 's/^PORT=.*/PORT=3002/' .env
curl -s -o /dev/null -w "%{http_code}" http://localhost:3002
```

Ожидаемый ответ: `200`. Найти занявший порт на Windows: `netstat -ano | findstr :3000`.

**Проблема. Агент запускает проект, а зависимостей нет**

- Ошибка: `Error: Cannot find module 'next'` или `sh: vite: command not found`
- Причина: `node_modules` игнорируется Git и в новый worktree не копируется — каталог содержит только отслеживаемые файлы.
- Решение: установите зависимости в каждом worktree из lock-файла:

```bash
cd ../myapp-agent-1 && npm ci
ls node_modules | head
```

Проверка: `ls node_modules` печатает список пакетов, повторный запуск дев-сервера проходит без ошибки.

## Резюме и следующие шаги

Связка «ветка на агента + отдельный worktree + свой порт и `.env`» даёт параллельную работу без взаимных перезаписей файлов при одном общем `.git`. Дальше закрепите процесс: опишите правила в `CLAUDE.md`, чтобы каждый агент знал границы своего каталога, и добавьте чек-лист приёмки в pull request. Если работа с ветками через Git кажется слишком шумной для параллельных агентов, сравните альтернативу в гайде [Jujutsu или Git: что выбрать для работы с ИИ-агентами и Claude Code](https://ai-release.org/guides/jujutsu-ili-git-chto-vybrat-dlya-raboty-s-ii-agentami-i.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).

## FAQ

**Можно ли запустить двух агентов в одном каталоге без worktree?**
Технически — да, но они будут редактировать одни и те же файлы и один индекс Git: правки одного затрут правки другого, а `git status` покажет смесь изменений. Worktree разводит файлы и индексы по разным каталогам при общей истории.

**Чем worktree отличается от обычного `git clone`?**
`clone` создаёт полную независимую копию репозитория вместе с `.git` и своей историей; синхронизировать её нужно через `fetch`/`push`. `worktree` использует тот же `.git`, поэтому коммиты сразу видны во всех каталогах, а диск не тратится на дублирование объектов.

**Нужно ли заново устанавливать зависимости в каждом worktree?**
Да. `node_modules` (или `.venv` для Python) не отслеживается Git и физически отсутствует в новом каталоге. Ставьте их из lock-файла: `npm ci` — это гарантирует одинаковые версии пакетов во всех worktree.

**Что будет, если просто удалить каталог worktree вручную?**
Git продолжит считать его существующим: `git worktree list` покажет путь, а `git worktree add` на освободившееся имя может ругаться. Убирайте корректно — `git worktree remove <путь>`, а если каталог уже удалён, выполните `git worktree prune`, чтобы очистить служебные записи.
