How do I run parallel Claude Code agents without intent conflicts?

Claude Code parallelizes with subagents, agent view, experimental agent teams, projects, and dynamic workflows (Run agents in parallel). “Intent conflicts” is user JTBD language, and Anthropic has no official product term or intent-publish API [GAP]. Official docs prevent file overwrites by choosing the lightest surface, partitioning file ownership, using worktree isolation for editors, and (for teams) a shared task list with claim locking. Enable agent teams only with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Prefer subagents + worktrees first; teams cost ~7× more tokens in plan mode (Manage costs).

Pick the right parallel surface

From the agents hub (fetched 2026-09-22):

Supporting: git worktrees; cross-session messaging; packaged /batch (5–30 worktree-isolated subagents → PRs).

Start with subagents (or agent-view / worktrees for independent edits). Escalate to agent teams only when peer messaging and a shared task list are worth the token cost. Use dynamic workflows for dozens of scripted workers. Projects are a separate cloud boundary: this is a one-line callout only.

Stop write collisions (the “intent” problem)

[GAP] Claude Code has no first-party “publish intent / claim semantic scope” protocol. Map the JTBD to official levers:

1. Lightest surface: subagents or worktrees before teams (agents, agent teams).
2. Partition ownership: each worker owns a different set of files. Docs: two teammates editing the same file → overwrites.
3. Worktree isolation: isolation: worktree on subagent frontmatter, or ask Claude to use worktrees; agent-view dispatches get a worktree before edits (worktrees). Agent teams do not auto-worktree teammates [GAP].
4. Task-list locking: claim locking so two teammates don’t take the same task (agent-teams architecture).
5. Plan / read-only first: spawn workers in plan mode for risky work; research before parallel writes.
6. CLAUDE.md / AGENTS.md boundaries: loaded into every teammate/subagent (unless omitClaudeMd); put ownership rules in project instructions. See share AGENTS.md / CLAUDE.md.
7. Shut down finished workers: idle teammates keep burning tokens (costs).

Community awareness only: HN Show HN Foremerge (2026-09-21) discusses local intent/scope coordination. It is not Anthropic product truth and not a required install.

Turn agent teams on safely

Teams are off by default. Enable only when needed:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Or shell: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Without it: no team setup, no team dirs, Claude does not spawn or propose teammates (agent teams).

Side effect: while teams are enabled, a named Agent-tool spawn from the lead can become a teammate even if you asked for a subagent. Set the env var to 0 to restore ordinary subagent behavior.

Non-interactive / Agent SDK: with -p or SDK sessions, Claude does not spawn teammates; a named subagent stays ordinary even if the env var is set (SDK subagents).

Cost and size: ~7× tokens vs standard when teammates run in plan mode (costs). Prefer Sonnet teammates; start 3–5 (guidance, not a hard cap [GAP]); shut down finished agents. Parallel burn hits the shared subscription pool: see rate limits. Effort × N workers: max effort level.

Subagent concurrency (CLI): default max 20 (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS); depth default 3 (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH) (subagents). For dozens–hundreds of agents, use dynamic workflows, not turn-by-turn Agent calls.

Pitfalls

• Leaving agent teams always-on (token burn + accidental teammate spawn).
• Same-file parallel edits without worktrees or an ownership split.
• Treating HN Foremerge or third-party walkthroughs as Anthropic product truth.
• Claiming SDK -p sessions spawn agent-team teammates.
• Inventing a hard teammate cap or an Anthropic “intent API.”

FAQ

Subagents or agent teams?

Subagents for focused side tasks that report a summary back. Teams when peers must discuss and coordinate (experimental env var). See agent teams and subagents.

How do I stop two agents editing the same file?

Partition file ownership. For subagents set isolation: worktree or use worktrees / agent-view dispatches. Teams do not auto-isolate in worktrees.

How do I turn agent teams on?

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in settings.json env or shell. Off by default.

Why did Claude spawn a teammate when I wanted a subagent?

With teams enabled, a named Agent spawn from the lead can launch as a teammate. Set the env var to 0 to restore ordinary subagents.

Do parallel agents get separate rate-limit pools?

No on subscription /login: shared five-hour + weekly pool; each worker burns its own context against that pool. Details: rate limits.

Sources

Checked 2026-09-22.

• Run agents in parallel
• Orchestrate teams of Claude Code sessions
• Create custom subagents
• Git worktrees
• Manage costs effectively
• Subagents in the Agent SDK
• Discourse only: HN Foremerge Show HN 49789356