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

sed — для него дан отдельный вариант)git worktree --help; команда должна вывести справку, а не ошибкуclaude --versiontmux (Linux/macOS) для параллельных сессий: tmux -V; на Windows проще открыть несколько окон PowerShell.git из истории, но каждый каталог получит свою копию node_modules (для типового фронтенд-проекта это сотни мегабайт)Пример: проект лежит в /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 отдельно.
Что сделать: создайте по каталогу на агента, каждому — своя ветка.
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`) | не нужен |

Что сделать: откройте отдельную терминальную сессию на каждый каталог и запустите в каждой 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: команда агентов от задачи до релиза.

Что сделать: убедитесь, что ветки разошлись, тесты зелёные в каждой, и только потом мерджите.
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 list показывает main + по строке на каждый агентский каталог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'refs/heads/....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.env из основного каталога с одинаковым PORT=3000..env в каждом каталоге отдельно, файл в .gitignore и не мерджится: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 foundnode_modules игнорируется Git и в новый worktree не копируется — каталог содержит только отслеживаемые файлы.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.
Можно ли запустить двух агентов в одном каталоге без 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, чтобы очистить служебные записи.
Статус: практическое руководство. Часть утверждений — заявления вендоров и проектов; проверяйте на своей среде.
Пошаговая инструкция по параллельному запуску нескольких агентов Claude Code в одном репозитории с изоляцией через git worktree, общими настройками и без конфликтов в файлах. Время выполнения: 25–30 минут Уровень сложности: Intermediate
Машинные данные публикации: Citation Map JSON · JSON-LD · Semantic Embeddings — отдельный этап.
| Сущность | Тип | Роль в публикации |
|---|---|---|
| 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 или разделах гайда |
В материале нет отдельного независимого подтверждения; ниже разделены заявления источников и редакционные выводы.
| Источник | Тип | Роль |
|---|---|---|
| Внешние ссылки в материале не указаны | — | — |
Как цитировать: AI Release. Как запустить несколько агентов Claude Code одновременно в одном проекте: git worktree и изолированные workspace. ai-release.org.