← Все гайды AI Release
EN Подписаться на @ai_release1

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

Обновлено: 21.11.2026 · AI Release · @ai_release1
Как запустить несколько агентов Claude Code одновременно в одном проекте: git worktree и изолированные workspace

TL;DR

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

Требования и подготовка

Иллюстрация к разделу «Требования и подготовка»
Иллюстрация к разделу «Требования и подготовка»

Пример: проект лежит в /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, только чтение

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

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 локальные артефакты, чтобы они не приехали в чужие ветки при мердже:

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, посмотрите как настроить субагентов и общий ИИ-суперагент — эти настройки применяются в каждом worktree отдельно.

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

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

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 не привязан к ветке):

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

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

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

Вариант для Windows 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. Запустите агентов параллельно»
Иллюстрация к разделу «Шаг 2. Запустите агентов параллельно»

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

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

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

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: команда агентов от задачи до релиза.

Шаг 3. Проверьте изоляцию и сведите результат

Иллюстрация к разделу «Шаг 3. Проверьте изоляцию и сведите результат»
Иллюстрация к разделу «Шаг 3. Проверьте изоляцию и сведите результат»

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

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 по отдельности:

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

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

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

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 add ../myapp-agent-3 -b agent/3-ui
# либо только для ревью, без ветки:
git worktree add --detach ../myapp-review-2 origin/main

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

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

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.

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

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.

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, чтобы очистить служебные записи.

🤖 Кратко для ИИ

AI Release Knowledge Layer
Машинно-читаемое описание публикации · Версия 1.0

Статус: практическое руководство. Часть утверждений — заявления вендоров и проектов; проверяйте на своей среде.

1. Суть публикации

Пошаговая инструкция по параллельному запуску нескольких агентов Claude Code в одном репозитории с изоляцией через git worktree, общими настройками и без конфликтов в файлах. Время выполнения: 25–30 минут Уровень сложности: Intermediate

Внутри: прямые ответы, ключевые факты, участники, связи, достоверность, неизвестное и источники.

Машинные данные публикации: Citation Map JSON · JSON-LD · Semantic Embeddings — отдельный этап.

Полный Knowledge Layer: разделы 2–8

2. Прямые ответы

Что это за материал?
Пошаговая инструкция по параллельному запуску нескольких агентов Claude Code в одном репозитории с изоляцией через git worktree, общими настройками и без конфликтов в файлах. → подробнее (AR-GUIDE-KAKZAPUSTI-001)
Что понадобится?
ОС: Linux, macOS или Windows (в Windows все команды ниже выполняются в PowerShell, кроме sed — для него дан отдельный вариант); Git — проверьте git worktree --help; команда должна вывести справку, а не ошибку; Claude Code CLI — проверьте claude --version; tmux (Linux/macOS) для параллельных сессий: tmux -V; на Windows… → подробнее (AR-GUIDE-KAKZAPUSTI-003)
Как это сделать?
Шаг 1. Создайте worktree под каждого агента → Шаг 2. Запустите агентов параллельно → Шаг 3. Проверьте изоляцию и сведите результат → подробнее (AR-GUIDE-KAKZAPUSTI-004)
Что может пойти не так?
Ошибка: fatal: 'agent/1-auth' is already checked out at '/home/user/projects/myapp-agent-1' → подробнее (AR-GUIDE-KAKZAPUSTI-006)

3. Ключевые факты

  1. Время выполнения: 25–30 минут — подтверждение; статус: заявление источника.
  2. Уровень сложности: Intermediate — подтверждение; статус: заявление источника.
  3. Понадобится: Git с поддержкой git worktree (проверяется командой git worktree --help; если выдаёт git: 'worktree' is not a git command — обновите Git до версии из документации вашего дистрибутива), Claude Code CLI (claude --version), терминал, tmux или несколько окон терминала, Node.js/npm — если проект на JavaScript — подтверждение; статус: заявление источника.
  4. Результат: N независимых рабочих каталогов на одну историю Git, в каждом — свой агент, своя ветка и свой порт дев-сервера — подтверждение; статус: заявление источника.
  5. ОС: Linux, macOS или Windows (в Windows все команды ниже выполняются в PowerShell, кроме sed — для него дан отдельный вариант) — подтверждение; статус: заявление источника.
  6. Git — проверьте git worktree --help; команда должна вывести справку, а не ошибку — подтверждение; статус: заявление источника.
  7. Claude Code CLI — проверьте claude --version — подтверждение; статус: заявление источника.
  8. Ошибка: fatal: 'agent/1-auth' is already checked out at '/home/user/projects/myapp-agent-1' — подтверждение; статус: анализ AI Release.
  9. Причина: Git запрещает держать одну ветку в двух worktree одновременно — иначе два индекса писали бы в одну ссылку refs/heads/.... — подтверждение; статус: анализ AI Release.

4. Участники и сущности

СущностьТипРоль в публикации
Claude Code несколько агентовтема/инструментупоминается в заголовке, TL;DR или разделах гайда
git worktree Claude Codeтема/инструментупоминается в заголовке, TL;DR или разделах гайда
изолированные workspaceтема/инструментупоминается в заголовке, TL;DR или разделах гайда
Windowsплатформа/технологияупоминается в заголовке, TL;DR или разделах гайда
Linuxплатформа/технологияупоминается в заголовке, TL;DR или разделах гайда
macOSплатформа/технологияупоминается в заголовке, TL;DR или разделах гайда
Node.jsплатформа/технологияупоминается в заголовке, TL;DR или разделах гайда
npmплатформа/технологияупоминается в заголовке, TL;DR или разделах гайда
Gitплатформа/технологияупоминается в заголовке, TL;DR или разделах гайда
Claudeтема/инструментупоминается в заголовке, TL;DR или разделах гайда

5. Связи и контекст

  • Гайд — описывает → Как запустить несколько агентов Claude Code одновременно в одном проекте: git worktree и изолированные workspace (AR-GUIDE-KAKZAPUSTI-001).
  • Гайд — содержит шаг → Шаг 1. Создайте worktree под каждого агента (AR-GUIDE-KAKZAPUSTI-001).

6. Достоверность и происхождение информации

Подтверждено

В материале нет отдельного независимого подтверждения; ниже разделены заявления источников и редакционные выводы.

Заявление источника

  • Характеристики продуктов, версии, цены и лимиты — из описаний вендоров и материалов гайда.
  • Команды и шаги приведены как рекомендация, а не как гарантированный результат.

Анализ AI Release

  • Структура, сравнение и критерии выбора — редакционные.
  • Гайд не заменяет независимый аудит или юридическую консультацию.

7. Что пока неизвестно

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

8. Источники

ИсточникТипРоль
Внешние ссылки в материале не указаны——

Как цитировать: AI Release. Как запустить несколько агентов Claude Code одновременно в одном проекте: git worktree и изолированные workspace. ai-release.org.