Parallel Claude Code Work: worktree, Agents, and Workflows

Practical materials on working with agents in parallel: Ailoot documentation.

This guide brings together practical experience and a map of where the tools apply. The four official Claude Code primitives, a map of where they apply, and an anti-hype framework for how many parallel agents a vibe coder actually needs. All figures and quotes link to primary sources from Anthropic.

What is multi-agent in Claude Code, and why isn't it “1000 agents”#

A multi-agent setup is one where a task is split into several independent work streams, each handling its own part and returning a result. The simplest example: you write the frontend in one Claude Code window, and the backend in another window on the same machine, with a shared git repository between them. That's already multi-agent, even though “orchestration” would be an unnecessary word for it.

A more involved setup: within one Claude Code session, you launch five subagents with different roles (frontend developer, backend developer, security reviewer, tester, documenter), and each returns its piece of the result to the shared conversation. It's the same multi-agent approach, just with one control point.

More involved still: you tell Claude, “run a weekly security audit of all 500 files in my project,” and it writes a JavaScript orchestrator script. The runtime launches several dozen agents in the background, each audits its own section, then independent agents check one another's findings, and you get one report back. That's Dynamic Workflows, released by Anthropic on May 28, 2026. A detailed feature breakdown is in the separate guide to Dynamic Workflows.

The difference between these three scenarios isn't the number of agents. The difference is who decides what the next agent does. In the first scenario, it's you. In the second, Claude decides as the conversation progresses. In the third, it's a JavaScript script that Claude wrote.

“1000 agents” is, by the way, a real figure. It's the upper limit for one Dynamic Workflow in Claude Code. The official Anthropic documentation says:

In other words, this is a technical safeguard against runaway behavior, not a recommended workload. In practice, 95% of tasks are handled by 2–8 parallel work streams. If you're planning more, first ask yourself what they'll be doing.

4 Claude Code primitives: subagents, skills, agent teams, workflows#

Claude Code has four official primitives for splitting one task across multiple agents. Anthropic brought them together in a comparison table in the Dynamic Workflows documentation. Here's the comparison in plain language:

Each of these primitives solves a different problem. Subagents are for delegating 2–3 checks within one task. Skills are for when you have a ready-made instruction Claude should follow (like “perform a PR review using this checklist”). Agent teams are for when several parts of a product live in different windows and you need one coordinator. Workflows are for when a task is too large for one context window.

Subagents are covered in detail in the Claude Code Subagents 2026 guide. The decision tree for “what to use for a particular task” is in the Skills, Subagents, MCP, Plugins guide. This guide is about assembling them into a multi-agent setup on top of git worktree.

Level 1: subagents in one session—the easiest place to start#

A subagent is the simplest way to split a task. The main conversation is the coordinator. Subagents are temporary workers the main agent launches as the work progresses.

A specific example from the project described. After the first draft of a guide, the review is set up like this: Claude gets the request, “launch six subagents in parallel—one checks for AI markers, the second for legal vocabulary, the third for voice and tone, the fourth checks facts with WebFetch, the fifth reviews SEO structure, and the sixth checks cross-link accuracy.” Each returns a report, after which the edits are applied.

Technically, this is done with files in .claude/agents/[subagent-name].md describing the role and tools. The call is made through the Agent tool in the main conversation. Claude decides when to send a request to a subagent.

Where it works. Tasks involving 3–7 parallel checks of one artifact (code, text, design). Each check is independent. The results fit in the main context window.

Where it breaks down. If you have 50+ files or each check needs its own 50K-token context, the main window will fill up. You need workflows or agent teams.

Main risk. Each subagent consumes tokens separately. If you launch six on a 200-file project and each rereads all 200, you pay 6×. So you MUST specify exactly which files the subagent should inspect. See the Where the Tokens Go in Claude Code guide for details.

Level 2: git worktree—isolating files between parallel sessions#

When subagents aren't enough and you need two full-fledged Claude Code instances in different terminals working on the same repository, a classic problem comes up. They start editing the same file; one saves first, and the second writes over it. A client asked the support team last week, “5 are overwriting each other at the same time.”

The solution is git worktree. It's a built-in git feature that lets you have several working copies of the same repository, each on its own branch, sharing a .git repository. One origin, different directories on disk, with no overlap between their files. The mechanism itself is described in detail in the Git worktree in Claude Code guide.

Commands for a five-minute setup:

# From the main project directory
cd ~/projects/my-app

# Create a worktree for feature/auth
git worktree add ../my-app-auth feature/auth

# Create a worktree for feature/billing
git worktree add ../my-app-billing feature/billing

# Open two terminal windows
cd ~/projects/my-app-auth && claude   # first Claude Code
cd ~/projects/my-app-billing && claude # second Claude Code

Each copy is on its own branch. Each Claude Code instance writes to its own directory. When the task is done, run git push from its branch, then git worktree remove ../my-app-auth.

What you need to know. A worktree does not duplicate node_modules, .venv, or other files in .gitignore. If you need independent dependencies (a different library version on each branch), run npm install separately in the new directory after worktree add.

How many worktrees per person. Based on team surveys from 2026, the practical ceiling is 4–8 parallel worktrees per developer. The limiting factor isn't Claude, but a person's ability to review and accept the results. If you have 10 worktrees, they're waiting for review.

In the practice described, people usually use 2–3 parallel worktrees. One primary worktree for active work, one backup for urgent hotfixes, and one for an experiment (a new feature you're unsure about). More aren't needed.

Level 3: agent teams—several windows, one lead agent#

Agent teams are a relatively new primitive. The idea: one lead agent holds the shared plan as a task list, and several peer sessions in separate windows take on tasks assigned by the lead. They all work on the same filesystem and can see one another's intermediate artifacts.

This is useful when a task breaks into 3–5 large work streams, each lasting hours (migrating a large module, rewriting a subsystem, performing a full security audit). In that case, the lead agent keeps the plan in one shared task file at an absolute path outside the worktrees. Workers read that path and report results; only the lead updates statuses, avoiding competing writes to the coordination file.

Technically, agent teams are several windows running over git worktree with one shared planning point. In practice, 80% of people manage agent teams manually (as described above with worktree) and don't use a special “teams framework.” That's fine.

If you're unsure whether you need a special framework at all, you almost certainly don't. Use manual worktree and one lead agent in the main directory.

Level 4: Dynamic Workflows—Claude writes a JS orchestration script#

All three levels above keep the plan in a conversation: in the main agent's head or in the lead agent's task list. Dynamic Workflows move the plan into code. Claude expresses the task as a JavaScript script, the runtime runs it in an isolated environment, intermediate results live in script variables rather than in your context, and the session stays responsive while agents work in the background.

A specific example from the official documentation. You say:

ultracode: audit every API endpoint under src/routes/ for missing auth checks

Claude writes a JavaScript script with roughly this logic: “take all files from src/routes/, split them into groups of 30 endpoints, run an agent on each group with the same check, then run two independent grader agents on their findings, and consolidate a final report.” It runs. You get a table of results and a list of endpoints that definitely need review.

Where it works.

• Auditing an entire project for one issue (security, typing, deprecated APIs).
• Large migrations (500+ files governed by a shared rule).
• Research questions that need to be checked from several independent angles (Anthropic does this in its built-in /deep-research command).

A detailed breakdown of Dynamic Workflows, their limits, and how ultracode works is in the separate guide to Dynamic Workflows in Claude Code.

When NOT to use it. When the task is linear and clear. A workflow isn't needed for a task like “finish this component.” A workflow makes sense when a task breaks into 10+ independent subtasks and you need cross-checking between them.

Main limitation. A workflow consumes significantly more tokens than a regular session. Anthropic recommends in its documentation:

In other words, run your first workflow on one directory, not the whole project. See what it cost, then decide whether it's worth scaling up.

Outcomes: a rubric of criteria and an independent reviewer#

The most dangerous thing in multi-agent work is trusting agents' outputs. Each agent returns text that looks like completed work. A quote seems true, a report seems complete, a migration seems done. With one agent, you can check it yourself. With 10, you can't—you won't have time.

Anthropic addresses this problem with Outcomes, a Managed Agents feature released May 6, 2026. The idea is simple: the session gets a SECOND agent (a grader) whose only job is to check the first agent's work against a strict rubric.

How it works technically. You write a rubric—a markdown document with a detailed list of what “done” means, which sources to check, and which labels to use. The platform automatically creates a grader agent in a fresh context window. It receives only the rubric and the result, nothing else. After every attempt by the main agent (the writer), the grader rereads the result and either passes it or returns an itemized list of what remains incomplete.

A quote from the Anthropic Cookbook:

Real impact figures: after integrating Outcomes into Claude Managed Agents, AI company Harvey's task completion rate increased by about 6×. At Wisedocs (medical documentation), the time spent reviewing a document decreased by 50%. These figures are from the official feature announcement.

What matters for a vibe coder rather than an enterprise. Outcomes is a pattern, not just a specific feature. You can create your own grader agent by describing the same criteria in .claude/agents/grader.md and asking the main agent to run it after every attempt. This works with any multi-agent setup, not just Managed Agents.

The main rubric-writing rule from the cookbook is to specify something verifiable, not something general. Not “check that the brief covers billing,” but “open the brief, find the section about billing, and confirm that it specifies an amount in $ or a percentage of revenue.” The first instruction lets the grader skim and check a box. The second makes it open the document and find a specific number.

Anti-pattern: “50 agents doing nonsense”#

This is the central multi-agent anti-pattern. Someone learns that Claude Code can run 16 agents at once, and Dynamic Workflows can run 1000 per run, so they sit down and launch them. The effect: zero. Token consumption: 10× an ordinary session.

A simple test. Take a sheet of paper and draw a box for each of your agents. In each box, write:

1. What exactly it does (one sentence).
2. Which files it touches.
3. What it returns.
4. Who checks it.

If you can't answer even one of these in 30 seconds, you shouldn't have that agent. This rule works at every level: subagents, agent teams, Dynamic Workflows.

The second anti-pattern is running in parallel work that should be sequential. If the frontend needs the backend first because it reads the API schema, don't run them in parallel. Do the backend first, then the frontend. Tasks should be parallel only if they're independent.

The third anti-pattern is using multi-agent for speed. This only works up to a point. If you split a task into four independent work streams, they'll finish in about the time one stream would take (plus minimal coordination overhead). But if there are 50 streams on one machine, each runs more slowly because they're sharing the CPU. The practical ceiling on a laptop is 4–6 concurrent Claude Code instances; after that, throttling starts.

How much does it cost, and how can you avoid burning through your limits?#

In May–June 2026, the industry faced the reality that AI coding cost more than expected.

One ordinary Claude Code chat session costs a relatively reasonable amount. Turn on Dynamic Workflows for an entire repository, and you get a bill 20× as high. From the official Anthropic documentation:

What to do in practice. The savings rules from the practice described.

1. Specify the files for each agent precisely. Not “look over the project and find problems,” but “look at src/auth/*.ts and check that every function validates userId.” The second prompt will give you exactly the work you're paying for.

2. Always try a workflow on one directory first. Not all of src/. Start with src/auth/. If you like the results and understand the cost, then roll it out more broadly.

3. Use /effort high by default, and ultracode only deliberately. /effort ultracode means xhigh plus automatic orchestration. It's very expensive. Use it when a task really requires several parallel work streams.

4. Switch subagents to a smaller model where you can. If you have six subagents reviewing one guide, neither the QA agent checking for AI nor the Cross-link checker needs Opus. Sonnet will do. This reduces usage by 3–5×.

A detailed look at saving tokens is in the Where the Tokens Go in Claude Code guide and How Not to Burn Through Claude Code Limits.

Where to start today: a 30-minute checklist#

1. Update Claude Code to v2.1.154+

   This is the minimum version that supports Dynamic Workflows. Run claude update in the terminal.

2. Enable Dynamic Workflows in /config

   They're disabled by default on the Pro plan. Open /config, find the “Dynamic workflows” line, and switch it on. They're already enabled on Max, Team, and Enterprise.

3. Create your first worktree

   In the main project directory, run git worktree add ../<project>-experiment <branch>. Open a second terminal window in that directory. Run claude.

4. Add a shared task list

   Use one absolute path outside all worktrees. A tasks.md in each worktree is a separate file and does not synchronize automatically. Let the lead session be the only writer; workers read the shared list and report results to the lead.

   Create the coordination directory and task list once:

   mkdir -p "$HOME/projects/my-app-coordination"
   printf '%s\n' '# Tasks' '- Auth: assigned to the auth worktree' '- Billing: assigned to the billing worktree' > "$HOME/projects/my-app-coordination/tasks.md"
   

   In the first terminal:

   cd "$HOME/projects/my-app-auth"
   printf 'Shared task list: %s\n' "$HOME/projects/my-app-coordination/tasks.md"
   claude
   

   In the second terminal:

   cd "$HOME/projects/my-app-billing"
   printf 'Shared task list: %s\n' "$HOME/projects/my-app-coordination/tasks.md"
   claude
   

   In both sessions, give the agent the same expanded absolute path printed above: “Read this shared task list. Work only on your assigned task and files. Do not edit the list; report completion and blockers to the lead, who owns updates.” Confirm that both agents can read that exact file before starting work; a permission prompt must be resolved for that path. The task list coordinates status, while code changes still remain in separate worktrees.

5. Work this way for a week

   Don't install a GUI wrapper right away. Spend a week working manually with two worktrees. You'll see what's missing; then choose a tool for a specific pain point.

6. Only then enable `/effort ultracode`

   Pick one task, such as “find all API endpoints without auth checks in src/routes/.” Enable /effort ultracode. See what workflow Claude writes, how much it costs, and what result it produces. That's your first Dynamic Workflow.

Where to go next: memory between sessions, Code Review, Multi-Agent v2#

What's appeared in May–June 2026, and where multi-agent in Claude Code is headed.

Managed Agents with Dreaming. Released May 6, 2026, at Code with Claude. A scheduled process that reads an agent's past transcripts between sessions, identifies recurring patterns, and updates its memory. AI legal company Harvey's task completion increased sixfold specifically after Dreaming. Still in research preview.

Outcomes as a Managed Agents feature. Described above. Available through the Claude Agent SDK, not directly in the Claude Code CLI. You can apply the same pattern manually using a grader subagent right now.

Multi-Agent Orchestration v2 in the Claude Agent SDK. A lead agent delegates subagents itself, using a shared filesystem. This is a step from “launch N subagents manually” to “describe a task, and the lead decides by itself whom to delegate to and how.” If you're just learning subagents, don't worry about v2 yet. Learn the classic pattern—“one main agent + 3–5 subagents with roles”—and move to v2 naturally in 3–6 months.

Code Review by a team of agents. Anthropic announced a feature at Code with Claude for automatic code review when a PR is opened. A team of AI agents checks the diff in parallel, searches for bugs, verifies findings with one another, and ranks them by severity. Available on Team and Enterprise, not yet on Pro.

Plugin Marketplace. Launched May 23, 2026, on v2.1.128-136. Some marketplace plugins are ready-made multi-agent setups (parallel-review, security-audit, migration-helper). You can install them with /plugin install <name>@claude-plugins-official and see how they're put together—a good way to learn how to write your own.

Multi-agent in Claude Code still looks like a set of primitives at different stages of maturity. Subagents and git worktree are stable, proven, and work everywhere. Agent teams are half-automated, half-manual. Dynamic Workflows are in research preview and changing rapidly. Managed Agents v2 is enterprise-only. That means that over the next year, the optimal setup for a vibe coder won't be the latest release, but the minimum setup needed for the specific task. Two worktrees and one grader subagent are enough for a month of active work. Add complexity only when you start to feel constrained.

A working setup for vibe coding#

Practical materials: Ailoot documentation.

More materials and tools: Ailoot.