Deepseek ArtifactsDeepseek Artifacts
Гайд по worktree

Worktree в Claude Code: параллельные сессии без конфликтов

Одна команда дает каждой сессии Claude Code собственную полную копию репозитория. Разбираем claude --worktree, структуру .claude/worktrees, изоляцию worktree у субагентов, очистку при выходе и случаи, когда ручной git worktree add все еще выигрывает.

Коротко

  • claude --worktree (короткая форма -w) запускает сессию внутри свежей копии репозитория в .claude/worktrees/<name> с чекаутом на ветке worktree-<name>.
  • Запускайте еще сессии в других терминалах, чтобы работать параллельно — каждая сессия правит свой каталог, при этом история и remote общие.
  • Субагенты тоже получают worktree: попросите обычным языком или пропишите isolation: worktree во frontmatter .claude/agents/*.md, чтобы включить навсегда.
  • При выходе чистые безымянные worktree удаляются автоматически, а с незавершенной работой — предлагаются к сохранению или удалению; результат сливайте обычным git merge ветки worktree-<name>.

Claude Code Worktrees in 7 Minutes

Канал: Developers Digest7:10

Смотреть

I'm using claude --worktree for everything now

Канал: Matt Pocock7:57

Смотреть

Worktrees — official documentation

Официальная документация: code.claude.com/docs

Смотреть

Каждый флаг, путь и поведение очистки на этой странице сверены с официальной документацией по worktree; видео выше — визуальные и фактические источники, включая prompt «keep/remove» при выходе и ловушку с push в main.

Скриншоты принадлежат их авторам и снабжены прямыми ссылками на точные таймкоды. Кадры с лицами не используются.

Работаем с worktree в Claude Code, шаг за шагом

Часть 1 — Первая изолированная сессия

  1. 1

    Подготовьте Git-репозиторий хотя бы с одним коммитом

    Worktree ответвляются от существующей истории, поэтому функции нужен настоящий Git-репозиторий. В новой папке выполните git init, создайте файл (в демо просто запускают touch index.html) и закоммитьте. Пропустите — и Claude Code будет не от чего ветвить.

    Terminal running git init in a demo-app folder with Initialized empty Git repository output and touch index.html, the one-commit starting point Claude Code worktrees require
    git init плюс touch index.html — одного коммита достаточно, чтобы claude --worktree заработал.Смотреть на 1:06
  2. 2

    Поймите, что такое worktree на самом деле

    Git-worktree — это второй рабочий каталог со своим чекаутом и своей веткой, который разделяет с репозиторием историю и remote. В отличие от переключения веток, ничего не уходит в stash: основной чекаут и каждый worktree остаются рабочими одновременно — ровно то, что нужно параллельным агентам.

    Worktrees diagram showing one Git repository fanning out into three folders labeled ../main, ../feature1 and ../feature2, each checked out on its own branch
    Один репозиторий, много рабочих папок: ../main, ../feature1 и ../feature2 одновременно сидят каждая на своей ветке.Смотреть на 0:30
  3. 3

    Запустите Claude Code с --worktree

    Изнутри репозитория выполните claude --worktree (или короткое claude -w). Claude Code создаст .claude/worktrees/<name>, сгенерирует имя вроде bright-tumbling-rabbit, если вы его не передали, и сразу поместит сессию в эту копию. В десктоп-приложении вы выбираете опцию worktree при старте сессии.

    Claude Code v2.1.50 welcome banner after launching claude --worktree in the demo-app repo, with the session working directory set to .claude/worktrees/bright-tumbling-rabbit
    В приветственном баннере видно, что рабочий каталог сессии уже внутри .claude/worktrees — дальше все происходит в копии.Смотреть на 1:22
  4. 4

    Откройте вторую сессию для второй задачи

    Снова выполните claude --worktree в другом терминале. Без имени вы получите еще один независимый worktree; передайте одно и то же имя дважды — откроется тот же. Теперь два агента могут править один проект одновременно, потому что каждый видит только свой каталог.

Часть 2 — Где живут файлы и команды

  1. 5

    Загляните в полную копию под .claude/worktrees

    Откройте папку в файловом менеджере: каждый worktree — полный чекаут со своим index.html, своим .claude/settings.local.json и своим файлом git, а тяжелая база объектов остается общей в главном .git. Поэтому поднять еще одну копию почти ничего не стоит.

    macOS Finder window listing .claude/worktrees with clever-munching-toast and spicy-napping-otter copies behind two browser tabs, each worktree holding its own git folder and index.html
    Два worktree на диске — clever-munching-toast и spicy-napping-otter — каждый полная копия проекта со своей папкой git и index.html.Смотреть на 1:50
  2. 6

    Убедитесь, что команды остаются внутри worktree

    Когда первая сессия открывает страницу в браузере, prompt разрешения показывает, что путь указывает в .claude/worktrees/clever-munching-toast — не в ваш основной чекаут. Claude Code также не дает субагентам править основной чекаут напрямую, и одну из этих проверок изоляции нельзя выключить.

    Claude Code permission prompt for an open command targeting .claude/worktrees/clever-munching-toast/index.html, showing the session working only inside its own worktree copy
    В диалоге подтверждения назван точный путь worktree: сессия один трогает только свою копию проекта.Смотреть на 1:42
  3. 7

    Именуйте worktree или ветвьтесь от PR (опционально)

    claude --worktree feature-auth создает предсказуемый именованный worktree, а повторный запуск с тем же именем открывает его снова, а не дублирует. Можно передать номер PR в кавычках (claude --worktree "#1234") или URL PR на GitHub/GitLab — получите worktree этого pull request в .claude/worktrees/pr-<number>.

Часть 3 — Параллельные субагенты и очистка

  1. 8

    Попросите параллельных субагентов с изоляцией worktree

    Изоляция масштабируется за пределы терминалов. Один промпт — «запусти пять разных субагентов, пусть создадут пять вариантов и используют изоляцию git worktree» — и Claude Code плодит агентов Task, каждый в собственном изолированном worktree, работающих с одним репозиторием одновременно без столкновений.

    Claude Code spawning five Task agents in parallel after a single prompt requesting creative SaaS landing page variations with git worktree isolation
    Пять агентов Task запускаются параллельно, каждый объявлен как работающий в собственном изолированном git-worktree.Смотреть на 2:42
  2. 9

    Наблюдайте, как каждый агент бежит в своей дорожке

    В списке задач видны все пять вариантов с вызовами инструментов и подсчетом токенов — прогресс можно отслеживать без пяти терминалов. Транскрипты субагентов не попадают в контекст основного потока, поэтому руководящая сессия остается компактной, пока агенты делают тяжелую работу.

    Claude Code task list with all five SaaS landing page subagents mid-run, each labeled with tool uses and token counts while isolated in its own worktree
    Все пять субагентов на середине забега — Variation 1 уже закончила с 50.3k токенов, остальные читают файлы в своих worktree.Смотреть на 3:42
  3. 10

    Сравните варианты и влейте победителя

    Когда агенты закончат, Claude Code перечислит каждый вариант с путем в .claude/worktrees/agent-<id>/ — можно открыть их рядом в браузере. Отправляйте понравившийся обычным git merge его worktree-ветки (или через PR) — конфликты, если будут, решаются как в любом Git-merge.

    Claude Code summary listing five landing page variations with their .claude/worktrees/agent-prefixed index.html paths next to a rendered dark FlowSync preview
    В сводке назван каждый вариант и его путь в .claude/worktrees, рядом со списком открыт один отрендеренный результат.Смотреть на 4:22
  4. 11

    Сохраните изоляцию как переиспользуемого субагента

    Чтобы изоляция worktree стала постоянной, просто попросите: «создай субагента фронтенд-разработчика, используй модель Haiku и пусть применяет изоляцию worktree». Claude Code изучит собственную документацию по агентам и запишет новый файл в .claude/agents/.

    Claude Code accepting a natural-language request to create a front-end developer subagent with Haiku that leverages work tree isolation
    Достаточно естественного языка — перед записью файла Claude Code сверяется со своей документацией по кастомным агентам.Смотреть на 5:42
  5. 12

    Проверьте frontmatter isolation: worktree

    В сгенерированном frontend-dev.md есть name, description, model: haiku, белый список инструментов и — новая строка — isolation: worktree. Теперь каждый запуск этого субагента идет во временном worktree, который автоматически удаляется, если тот закончил без изменений.

    Claude Code writing the .claude/agents/frontend-dev.md subagent file with isolation: worktree in its YAML frontmatter so every future run gets its own worktree
    Строка 8 frontmatter — isolation: worktree — именно она дает каждому запуску этого субагента собственный worktree.Смотреть на 6:42
  6. 13

    Влейте изменения и оставьте уборку Claude

    Когда вы выходите из сессии, Claude Code осматривает worktree: чистые безымянные удаляются автоматически, а с работой предлагает сохранить или удалить — при сохранении печатает команду claude --worktree <name> --resume на будущее. Headless-запуски -p никогда не убирают за собой, такие удаляйте через git worktree remove.

Worktree в Claude Code vs ручной git worktree add

Worktree существуют в Git уже годы — новое в том, что Claude Code управляет всем их жизненным циклом. Различия, которые важны:

  • 1Создание: вручную вы запускаете git worktree add ../project-feature -b feature, делаете cd и стартуете Claude. С claude --worktree сессия за один шаг оказывается внутри .claude/worktrees/<name>, с именем от вас или сгенерированным.
  • 2Базовый коммит: worktree.baseRef управляет стартовой точкой — fresh (по умолчанию) ветвится от дефолтной ветки удаленного репозитория, head тащит ваши незапушенные локальные коммиты. Флага для конкретной ветки нет; документация советует в этом случае ручной git worktree add.
  • 3Dotfiles: файл .worktreeinclude в корне проекта копирует проигнорированные git-ом файлы вроде .env в каждый новый worktree. Ручные worktree этого бонуса не получают.
  • 4Очистка: Claude Code при выходе осматривает worktree, автоматически удаляет чистые безымянные, спрашивает перед тем как трогать незавершенную работу и периодически выметает брошенные worktree субагентов. Ручные worktree — целиком ваша ответственность.
  • 5Ограждения: проверки изоляции не дают субагентам править основной чекаут, а возобновление сессии возвращает вас в ее worktree. У голого git worktree add такой страховки нет.

Под капотом это по-прежнему обычный Git. Панель управления исходниками в VS Code показывает каждый worktree со своими изменениями, слияния — обычные git-мержи, а ручные и клодовские worktree сосуществуют в одном репозитории — выбирайте инструмент под задачу.

Когда worktree ведет себя не так

Большинство граблей — это основы Git, проступающие сквозь функцию, а не баги. Эти пять покрывают почти все острые углы:

  • 1Push уезжает в main. Свежая worktree-ветка трекает дефолтную ветку origin, поэтому голый git push может целиться в main. Пушьте явно: git push origin worktree-<name>, и держите main под защитой.
  • 2Не хватает файлов или инструментов. Проигнорированные git-ом файлы (.env, каталоги vendor) и локальные для репозитория filter drivers вроде LFS не переносятся в новый worktree. Перечислите их в .worktreeinclude или выполните git lfs pull и свои команды настройки внутри worktree.
  • 3Запуск падает с ошибкой доверия. В недоверенном каталоге claude --worktree завершится ошибкой с предложением сначала принять workspace — примите и перезапустите. (Неинтерактивные запуски -p проверку пропускают.)
  • 4Два worktree сталкиваются при слиянии. Если обе задачи правят один файл — маршруты, сайдбар, package.json — конфликты при слиянии решаются как в любом Git-процессе. Worktree убирают столкновения по ходу работы, но не пересекающиеся замыслы.
  • 5Оставшиеся worktree после headless-запусков. Запуски -p за собой не убирают; удаляйте вручную через git worktree remove (сначала git worktree unlock, если worktree залочен).

Удалить worktree из-под сессии тоже не смертельно: следующий resume откатится в стартовый каталог, привязка сбросится. Остальное в сессии не ломается.

FAQ

Похожие гайды по Claude Code