AI Teams: Multiple Agents Working Together

AI Teams: Multiple Agents Working Together

!!! info “This is advanced territory” You don’t need multi-agent systems for most tasks. Read this when you’re comfortable with headless mode and have hit the limits of what a single Claude instance can do. If you’re just getting started, bookmark this and come back later.

What is an agent?

In everyday usage, “agent” just means a Claude instance with a specific job and the tools to do it.

When you open Claude Code and start working on something, you’re the one directing it turn by turn. An agent is a Claude instance that can direct itself — it receives a goal, breaks it down, uses tools, and works toward the outcome without you guiding every step.

One agent can do a lot. But some problems benefit from having more than one.

Why multiple agents?

Think about how teams work. You don’t have one person responsible for writing code, reviewing it, testing it, and deploying it simultaneously. Those are different jobs, sometimes happening in parallel, requiring different focus.

Multi-agent systems apply the same logic to AI:

• Parallel work — two agents working on independent tasks simultaneously finish in half the time
• Specialization — each agent gets focused context, tools, and instructions for its job instead of one agent juggling everything
• Scale — some tasks are too large for a single context window; agents can divide the work
• Isolation — agents working in separate environments can’t accidentally break each other’s work

How it works in Claude Code

The orchestrator pattern

The most common multi-agent structure has one coordinating agent — the orchestrator — that delegates to worker agents:

Orchestrator (the one you talk to)
├── Agent A (Developer) → writes the code
├── Agent B (Reviewer)  → reviews the code
└── Agent C (Planner)   → researches the approach

The orchestrator:

1. Receives the goal from you
2. Breaks it into tasks that can be handled independently
3. Spawns sub-agents with specific instructions and tools
4. Waits for results (or runs them in parallel if independent)
5. Synthesizes everything and reports back

Spawning a sub-agent

The orchestrator spawns sub-agents using the Agent tool (built into Claude Code). In practice, you don’t write this code yourself — the orchestrator does it automatically when it determines a task should be delegated.

Under the hood, it looks like this:

# The orchestrator spawns a sub-agent via Claude's Agent tool
# Sub-agent gets a specific task, context, and tool permissions
claude -p "Analyze the security implications of this API design: [context]" \
  --max-turns 20 \
  --allowedTools "Read,WebFetch" \
  --output-format json

The sub-agent runs, produces output, and the orchestrator reads that output and continues.

Built-in agent types

Claude Code has several agent types you can invoke directly. Common ones:

Agent type	What it’s good at
Developer	Writing, editing, and debugging code
Planner	Research, analysis, producing structured plans
Explorer	Reading and mapping large codebases
General-purpose	Anything that doesn’t fit a specialized role

You can also define custom agent types in your CLAUDE.md with specific instructions, tool access, and personas.

Background vs. foreground

When you spawn a sub-agent, you can run it in the background (don’t wait for it, continue with other work) or foreground (wait for the result before continuing).

Foreground — use when you need the result before the next step:

Analyze this file and tell me what it does, then I'll decide what to change.

Background — use when the task is independent:

While you're working on the login page, spin up a sub-agent to handle
the password reset flow in parallel.

Parallel background agents are where you get real time compression on large tasks.

A real example walkthrough

Here’s how a multi-agent workflow actually unfolds in practice.

The request: “I need to build a small API that pulls my weekly calendar, formats it as a Markdown summary, and emails it to me every Friday.”

What happens:

1. You tell the orchestrator (your main Claude Code session) what you want.

2. The orchestrator recognizes this involves research, planning, coding, and testing — and that some of these can run in parallel.

3. It spawns two background agents:

   • Planner agent: researches the Calendar and Gmail MCP APIs, designs the architecture, writes a plan
   • Explorer agent: reads the existing project structure to understand what’s already there

4. Both run simultaneously. While you wait (a minute or two), both are working.

5. The orchestrator reads both results, synthesizes a plan, and confirms with you: “Here’s what I’m thinking — does this look right?”

6. You approve. The orchestrator delegates implementation to a Developer agent with the plan as context.

7. The developer agent writes the code, runs tests, fixes issues.

8. The orchestrator reviews the output, reports back to you with what was built and how to deploy it.

The whole thing might take 10–15 minutes instead of the hour it would take to do manually — and you only made one decision (approving the plan).

Worktrees: parallel work on the same codebase

One problem with parallel agents is collisions — two agents editing the same file at the same time creates chaos.

Git worktrees solve this. A worktree is an isolated copy of your repository that shares git history but has its own working files. Two agents can work on different features simultaneously without touching each other’s changes.

# Create a worktree for a feature branch
git worktree add ../my-project-feature feature/new-thing

# Agent 1 works in the main directory
cd /path/to/my-project
claude -p "Implement the login feature"

# Agent 2 works in the worktree simultaneously
cd /path/to/my-project-feature
claude -p "Implement the password reset feature"

When both are done, you merge the branches normally. Neither agent knew the other existed.

Worktrees are worth knowing about if you ever need multiple agents working on the same codebase at once. For most tasks — especially non-code tasks — they’re not needed.

When to use agents vs. just doing it yourself

More agents is not always better. Every sub-agent costs tokens, time, and coordination overhead. Use this heuristic:

Task type	Right approach
Simple, clear, one domain	Just do it in the current session
Research needed before action	Spawn one Planner agent, then proceed
Multiple independent workstreams	Parallel agents
Large codebase, multiple features	Agents with worktrees
Anything you could do in 5 minutes	Just do it yourself

The overhead of spinning up and coordinating agents only pays off when the tasks are complex enough or large enough that the parallelism or specialization genuinely helps.

!!! tip “Start with one sub-agent, not five” The first time you use multi-agent, spawn one sub-agent for one clearly isolated task. See how it works, review the output, understand the coordination overhead. Then add more as you understand the pattern.

Memory coordination across agents

Agents can share context through files. The pattern:

• Each sub-agent writes its findings to a file in the project directory
• The orchestrator reads those files to synthesize results
• Project-level CLAUDE.md provides shared context all agents can read

The key rule: avoid two agents writing to the same file at the same time. Structure the work so each agent has its own output file, and the orchestrator assembles the pieces.

project/
  agent-outputs/
    planner-findings.md      ← written by Planner agent
    security-review.md       ← written by Security agent
    developer-notes.md       ← written by Developer agent
  CLAUDE.md                  ← shared context, all agents read this

What’s possible at the far end

When you’re running a sophisticated multi-agent setup, you can have conversations that work like this:

“Research what the best approach is for X, have someone review it for security issues, then have the developer build it.”

One message. Three agents. The orchestrator decomposes, delegates, coordinates, and delivers. You made one decision and got a complete outcome.

That’s the vision. It takes time to get there — you need solid prompts, well-defined agent roles, and experience knowing when to delegate vs. when to just do it. But the building blocks are all in Claude Code today.