What Still Breaks After You Put Claude Code in Worktrees

Git worktrees solve the first parallel-agent problem: two Claude Code sessions no longer edit the same physical files. They do not isolate ports, external services, secrets, assumptions, review capacity, or the lifecycle of a long-running process.

Here are the seven failures that matter after file isolation is already working, plus the Agentastic pattern for each one.

1. The checkout exists but the application cannot run#

A new worktree contains tracked Git files. It usually does not contain .env, local certificates, virtual environments, generated clients, or installed dependencies.

The predictable failure is an agent spending its first turn reverse-engineering setup. Sometimes it guesses correctly. Sometimes it installs the wrong package manager, runs a migration against a shared database, or edits the project to work around a missing local file.

Fix: make setup an explicit repository contract.

Use .worktreeinclude with Claude's native worktrees for a small set of ignored files. In Agentastic, use .agentastic/setup.sh for copying local configuration, installing dependencies, generating code, and preparing per-worktree resources.

The setup script should be safe to rerun, visible when it fails, and fast enough that people do not bypass it.

2. Dev servers collide even though files do not#

Each worktree may contain a separate application, but every process still reaches the same host network. Three agents that all run npm run dev may all request port 3000.

The first server starts. The others fail, silently choose another port, or test the first worktree's application by mistake.

Fix: assign a stable port per worktree and surface it in the environment.

Derive a port from the branch or workspace identifier, reserve a range for agent work, and have the setup or run script write the selected value to a local environment file. The browser must open the URL belonging to the same worktree as the agent.

See environment setup for agent worktrees for an example.

3. A shared database turns isolated code into shared state#

Two agents can have perfect file isolation and still corrupt each other's test assumptions through one Postgres database, Redis instance, queue, object-storage bucket, or local emulator.

One branch migrates the schema while another runs tests against the old shape. One suite deletes fixtures the other expects. A test passes because another agent inserted the row.

Fix: choose one of four explicit service policies:

• One database or schema per worktree.
• One container stack per worktree.
• Transactionally isolated test databases.
• A serialized lane for tasks that must share a service.

Do not call work "parallel" if the most important mutable dependency remains shared without a coordination policy.

4. Agents start from different versions of reality#

An old local main can seed several worktrees with a bug that was already fixed remotely. Later, one branch merges and changes an API while the other worktrees continue against their original base.

Their tests may still pass locally. The integration failure appears only after merge.

Fix: make the base visible and update deliberately.

Agentastic's Start from origin option creates a worktree from the current remote commit without disturbing the main checkout. The diff remembers the creation point. After a dependency merges, update dependent branches and rerun their checks.

Parallel tasks should be independent by design, not merely launched at the same time.

5. A session list does not tell you what needs attention#

Five named sessions are better than five tabs called zsh. The hard question is still: which one is blocked right now, and why?

Polling every terminal defeats the purpose of background work. Terminal bells are also weak: they do not distinguish a clarification request from successful completion or failure.

Fix: route structured lifecycle events.

Agentastic maps supported Claude Code hooks such as permission requests, notifications, stop, and session end into running, waiting, finished, and failed states. The notification remains attached to the terminal and worktree that owns it.

Use Shift-Command-U to jump through sessions that need attention instead of scanning every transcript.

6. Parallel output overwhelms review#

Four agents can produce code faster than one person can validate it. The tempting response is to skim final summaries and merge on green tests.

That is where parallelism becomes risk amplification. Each agent has local context and a coherent story about why its change is correct. The reviewer needs evidence across all changed files and across interactions between branches.

Fix: budget review capacity and separate implementation from review.

• Keep tasks pull-request sized.
• Prefer independent file ownership.
• Inspect every diff.
• Run the worktree's verification command yourself.
• Use a fresh agent or dedicated reviewer after implementation.
• Lower concurrency when completed diffs queue faster than you can review them.

Agentastic can run Claude, Codex, CodeRabbit, Greptile, or custom review commands against the same captured diff. Multiple AI opinions still require human judgment.

7. Processes, worktrees, and context outlive the task#

Sessions can keep running after a window closes. Worktrees accumulate dependencies and caches. Remote tasks survive longer than the assumptions in their prompt. A branch that looked useful on Tuesday becomes unexplained disk usage on Friday.

Fix: give every workspace a terminal state.

At minimum, a task should end as one of:

• Merged and removable.
• Open as a pull request.
• Waiting on a named decision.
• Archived with a reason.
• Discarded and cleaned up.

Stop processes before removing local worktrees. Let container-backed workspaces remove their runtime. Keep remote sessions only when there is still an owner and a next action.

Worktrees are still the right default#

These problems do not make worktrees a bad isolation primitive. They show where their responsibility ends.

Use worktrees for normal repository isolation. Add setup scripts for reproducibility. Add containers when runtime or services need stronger boundaries. Add status and notifications when sessions exceed what you can remember. Add a review queue before adding more workers.

The complete system is:

If any arrow is manual and frequently forgotten, automate that arrow before increasing concurrency.

Download Agentastic for macOS or read How to Run Multiple Claude Code Agents in Parallel.

Sources and further reading#

• Run parallel sessions with worktrees — Claude Code
• Run agents in parallel — Claude Code
• Git worktree documentation
• Notifications — Agentastic Docs
• Setup & Teardown Scripts — Agentastic Docs