Running a Swarm: Multi-Agent Claude Code

Running a Swarm: Multi-Agent Claude Code

Part of the series: Claude Code: From Zero to Swarm

Why multiple agents?

One Claude Code session gives you one context window. One train of thought. One conversation doing one thing at a time.

For most tasks, that is exactly what you need. Fix a bug? One agent. Add a component? One agent. Refactor a module? One agent. The single-session workflow handles the vast majority of development work.

But some tasks have naturally independent parts.

Say you need a backend API and a frontend page. They share an interface — the API contract — but the actual implementation is independent. The backend needs database queries, validation, and route handlers. The frontend needs components, state management, and styling. These are two separate streams of work that happen to connect at one point.

If you run both in a single session, something interesting happens. By the time Claude gets to the frontend, it is carrying all the backend context: the database schema decisions, the middleware configuration, the error handling patterns. That context is still in the window, taking up space, pulling attention. Claude might start over-engineering the frontend to match patterns that only matter on the backend. The context from task one bleeds into task two.

This is context pollution. Not a catastrophic failure — just a gradual loss of focus. The session gets slower, the responses get longer, and Claude starts referencing things that are not relevant to the current task.

The solution is straightforward: multiple agents, each with a focused task and a clean context window.

One agent handles the backend. Another handles the frontend. Each starts fresh, with only the information it needs. When both finish, you combine the results.

This is the "swarm" in "Zero to Swarm." Not a single brilliant agent doing everything, but coordinated agents working together — each focused, each clean, each fast.

Git worktrees: isolated workspaces

Before you run multiple agents, you need to solve a practical problem: if two agents edit the same files in the same directory, you get conflicts. Agent one writes a file, agent two overwrites it, and now you have a mess.

Git worktrees solve this by creating isolated copies of your project. Same repository, same git history, but different working directories on disk. Each agent gets its own folder to work in.

Here is how it works.

You are in your main project directory, on the main branch. You want to create a separate workspace for a new feature:

git worktree add ../auth-feature auth-feature-branch

This does two things: creates a new branch called auth-feature-branch and checks it out in the directory ../auth-feature. Now you have two folders:

• Your original project directory (on main)
• The ../auth-feature directory (on auth-feature-branch)

Each folder is a fully functional copy of your project. You can open one Claude Code session in each directory, and they will never step on each other's toes.

When the work is done, you merge:

git merge auth-feature-branch

And clean up the worktree:

git worktree remove ../auth-feature

Think of it like giving each team member their own desk with their own copy of the documents. Everyone works independently. When they are done, someone collects everything and puts it together.

In Claude Code, you can ask it to set up worktrees for you. Just say: "Create a git worktree for the new authentication feature." Claude will run the commands, create the branch, and set up the isolated workspace. You can then open a second terminal, navigate to the worktree directory, and start a fresh Claude Code session there.

If you want to go further, you can create multiple worktrees:

git worktree add ../feature-api api-branch
git worktree add ../feature-ui ui-branch
git worktree add ../feature-tests tests-branch

Now you have four workspaces: your main directory and three feature directories. Four terminals, four Claude Code sessions, four agents working in parallel.

The key constraint to remember: each worktree must be on a different branch. You cannot have two worktrees on the same branch. This is actually a feature, not a limitation — it forces clean separation of concerns.

Subagents: Claude dispatching Claude

Git worktrees require you to set everything up manually — create the worktrees, open multiple terminals, start separate sessions, coordinate the results yourself. It works, but there is a more elegant approach built into Claude Code.

Claude Code can launch other Claude Code instances. These are called subagents.

The parent agent — your main session, the one you are talking to — acts as the coordinator. It analyzes the task, decides what can be done in parallel, and dispatches subagents to handle the independent pieces. Each subagent gets a focused brief: a specific task, specific files to work with, and a specific goal.

This happens in two ways.

Automatically. Claude analyzes your request and decides that it has independent parts. Without you asking, it breaks the work into subtasks and dispatches subagents. You see status messages as agents spin up, work, and report back. This typically happens when you give Claude a broad task like "add user authentication with signup, login, and password reset" — Claude recognizes that the database migration, the API routes, and the page templates are independent pieces.

On request. You explicitly ask: "Use subagents to handle the frontend and backend separately." Claude follows your instruction, creates the task breakdown you described, and dispatches accordingly.

Each subagent runs in isolation. It gets its own context window, its own conversation, its own working memory. It does not see what the other subagents are doing. It does not carry context from the parent session beyond the brief it was given.

When a subagent finishes, it reports back to the parent. The report includes what it did, what files it changed, and whether it encountered any issues. The parent agent reads these reports, decides if everything looks good, and either moves forward or dispatches follow-up work.

The mental model: you are talking to a team lead, not a solo developer. The team lead listens to your request, thinks about how to break it down, assigns work to specialists, and reports back with the combined result.

Parallel execution

The real power of subagents is that they run simultaneously.

While one agent builds the database schema, another writes the API endpoints, and a third creates the frontend components. They all start at the same time and work concurrently.

You (orchestrator)
├── Agent 1: Database schema    (5 min)
├── Agent 2: API endpoints      (8 min)
└── Agent 3: Frontend components (10 min)
Total: 10 min (not 23 min)

The total time equals the time of the longest task — not the sum of all tasks. A feature that would take 30 minutes sequentially might take 10 minutes with three parallel agents.

This math gets better as your tasks get more numerous and more uniform. Three tasks that each take 10 minutes: 30 minutes sequentially, 10 minutes in parallel. Five tasks that each take 6 minutes: 30 minutes sequentially, 6 minutes in parallel.

But the math only works when the tasks are truly independent. If agent two needs to read agent one's output before it can start, that is not parallelism — that is a pipeline. Running them "in parallel" just means agent two sits idle until agent one finishes, which is slower than running them sequentially because of the coordination overhead.

The practical ceiling is around three to five parallel agents for most tasks. Beyond that, the coordination cost starts to outweigh the speed benefit. Each agent needs a clear brief, the results all need to be integrated, and conflicts need to be resolved. With ten parallel agents, you spend more time coordinating than you save by parallelizing.

There is also a resource consideration. Each subagent uses its own context window, its own API calls, its own processing time. Running five agents costs roughly five times what one agent costs. The tradeoff is worth it when time matters more than compute cost — which, for most professional development work, it does.

The orchestrator pattern

The most powerful multi-agent pattern is simple: one agent coordinates, others execute.

The orchestrator is your main session. It understands the full picture. It has the project context, the goal, and the constraints. Its job is to break work into tasks, assign tasks to subagents, review results, and integrate everything into a coherent whole.

The executors are the subagents. Each one is a focused specialist handling a single piece of the puzzle. They do not need to understand the full picture — they need to execute their specific task well and report back.

This mirrors how effective teams operate. A technical lead who understands the architecture and project goals, and individual contributors who each own a piece of the implementation. The lead does not write every line of code. The contributors do not need to attend every planning meeting. Clear boundaries, clear communication, clear accountability.

The orchestrator's workflow looks like this:

1. Plan. Analyze the task and break it into independent pieces. Define what each piece needs to accomplish, what files it touches, and what the expected output looks like.
2. Dispatch. Launch subagents with focused briefs. Each brief is specific: "Create the database migration for a blog posts table with these fields. Put the migration in db/migrations/."
3. Wait. Let the agents work. Monitor progress.
4. Review. Read each agent's report. Check that the pieces fit together. Look for mismatches — naming inconsistencies, missing connections, conflicting assumptions.
5. Fix. If something does not line up, dispatch a follow-up agent to fix the specific issue. Do not redo everything — just patch the gap.
6. Integrate. Merge all the changes. Verify the whole thing works end to end.

The key discipline: the orchestrator does not do the implementation. The moment it starts writing code itself, it loses its coordination advantage. Its context window fills up with implementation details, and it can no longer see the big picture clearly. Let the orchestrator orchestrate. Let the executors execute.

A practical example

Let's walk through a realistic scenario from start to finish.

The goal: Add a blog section to an existing Next.js website. The site already has a homepage and an about page. You want to add a blog with a list page, individual post pages, and the ability to create and edit posts.

Step 1 — Plan

You tell Claude:

"I want to add a blog section to this website. It needs a data model, API routes for creating and reading posts, and page layouts for the list and detail views. Break this into parallel tasks."

Claude analyzes the codebase — checks the existing database setup, the routing patterns, the component library — and creates a plan:

• Task 1: Data model and migration. Create a blog_posts table with fields for title, slug, content, author, published status, and timestamps. Write the migration file.
• Task 2: API routes. Create CRUD endpoints — list all posts, get single post by slug, create post, update post. Follow the existing API patterns in the project.
• Task 3: Page layouts. Build the blog list page showing post titles, dates, and excerpts. Build the detail page rendering the full post content. Use the existing design system components.

Step 2 — Dispatch

Claude launches three subagents. Each gets a focused brief.

Agent 1's brief: "Create a database migration for a blog_posts table. Fields: id (UUID, primary key), title (text, not null), slug (text, unique, not null), content (text, not null), author (text, not null), published (boolean, default false), created_at (timestamp), updated_at (timestamp). Follow the existing migration patterns in db/migrations/. Also create the TypeScript type definition in types/blog.ts."

Agent 2's brief: "Create API routes for blog posts following the patterns in app/api/. Endpoints needed: GET /api/posts (list all published posts, sorted by date), GET /api/posts/[slug] (single post by slug), POST /api/posts (create new post), PUT /api/posts/[slug] (update existing post). Use the existing database client from lib/db. The post type will be defined in types/blog.ts — import from there."

Agent 3's brief: "Create the blog page layouts. app/blog/page.tsx for the list view: fetch posts from /api/posts, display as cards with title, date, and excerpt (first 150 characters of content). app/blog/[slug]/page.tsx for the detail view: fetch single post from /api/posts/[slug], render full content. Use the existing <Card>, <Container>, and <Heading> components from components/ui/."

Step 3 — Execute

All three agents start working simultaneously.

Agent 1 finishes first. Report: "Created migration 001_create_blog_posts.sql and type definition types/blog.ts. The type exports a BlogPost interface with all specified fields."

Agent 2 finishes next. Report: "Created four API routes following the existing patterns. All routes import BlogPost from types/blog.ts. List endpoint supports pagination with ?page= and ?limit= query parameters."

Agent 3 finishes last. Report: "Created blog list page and detail page. List page fetches from /api/posts and renders post cards. Detail page fetches from /api/posts/[slug] and renders full content with a back link."

Step 4 — Review

Claude reviews all three agents' output and finds an issue.

Agent 2 named the title field post_title in the API response (it wrapped the raw database fields in a response object with prefixed names). Agent 3 expects title in the frontend (because the brief said "title" and the type definition uses "title"). The API response does not match what the frontend expects.

Claude dispatches a fix: "In app/api/posts/route.ts and app/api/posts/[slug]/route.ts, return the database fields directly matching the BlogPost type from types/blog.ts. Do not rename fields in the API response."

The fix agent makes the two-line change and reports back.

Step 5 — Integrate

Claude verifies that all the pieces connect:

• The migration creates the table with the right fields.
• The type definition matches the table schema.
• The API routes return data matching the type definition.
• The frontend pages consume the API responses correctly.

Everything aligns. Claude runs a quick verification — checks that the files exist, the imports resolve, the types are consistent.

"Blog section added. Created database migration, four API routes, and two page layouts. All components use the existing design system. You can run the migration with npm run db:migrate and visit /blog to see it."

The key insight

You described what you wanted in plain English: "Add a blog section." The orchestration — breaking it into tasks, running them in parallel, catching the naming mismatch, fixing it, verifying the integration — happened through conversation. You did not write a task runner or a workflow file. You talked to an agent that knows how to coordinate.

When to use what

Not every task needs a swarm. Here is how to decide.

A few rules of thumb that come from practice, not theory.

Do not over-orchestrate. If one agent can handle the task in a single session, let it. Launching subagents adds coordination overhead. For a task that takes five minutes with one agent, splitting it across three agents might take seven minutes because of the dispatch and integration cost.

The sweet spot is two to four parallel agents. Three agents working on clearly separated concerns — database, API, frontend — is the pattern that pays off most often. You get meaningful time savings without significant coordination complexity.

More agents does not mean more speed. Ten parallel agents rarely helps. The integration step becomes the bottleneck. Every agent's output needs to be reviewed and merged, and the probability of conflicts and mismatches grows with every additional agent. Five agents can produce five conflicting approaches to the same problem.

If agents need each other's output, they are not independent. The whole point of parallel execution is independence. If agent two needs to read what agent one wrote before it can start, run them sequentially. Forcing them into parallel just means agent two either guesses (and guesses wrong) or waits (and wastes a context window on idle time).

Start with one agent and scale up. When you give Claude a task, start in a single session. If it becomes clear that the task has independent parts — "this backend work and this frontend work really have nothing to do with each other" — that is when you ask for subagents. You do not need to predict the right approach upfront. Let the work reveal the structure.

What you just learned

You started this series opening a terminal for the first time. You learned to navigate your filesystem, install Claude Code, and run basic commands. Then you opened a real project, understood its structure, and made changes. You learned context engineering — how to feed Claude the right information so it gives you the right output.

Now you have seen the other end of the spectrum: multiple agents working together. Worktrees for file isolation, subagents for parallel execution, and the orchestrator pattern for coordinating complex multi-part features.

The range between "fix this typo" and "build this feature with three parallel agents" is the range of Claude Code. Most of your day-to-day work will be single-agent sessions. Some of your most ambitious work will use the orchestrator pattern. Knowing that both options exist — and when to reach for each — is what makes you effective.

The "Zero to Swarm" journey is almost complete. You went from pwd to orchestrating multi-agent workflows.

The final article in this series steps back from the practical and looks forward. What happens when AI does not just help with individual tasks, but operates entire business functions? When the swarm is not just building features, but running operations? That is where this is all heading.