Your agent shouldn't work alone

The Forge

On May 31, a single Claude Code prompt spun up 70 research agents across four phases, with no orchestration code written by hand. The clip made the rounds, and the takeaway most people walked away with was the wrong one. The lesson is not "spawn 70 agents." The lesson is that running more than one agent at a time is now a built-in feature, not a weekend hack with a queue and a message bus.

Code with Claude 2026 shipped multi-agent orchestration as a first-class capability. Claude Code calls it Agent Teams. One session acts as team lead, the teammates each get their own context window, and they coordinate without you babysitting every step.

Here is the part nobody puts on the slide: a team of agents is not a free upgrade. It is a different tool with a different cost curve. Used well, it turns a four-hour serial slog into a 40-minute parallel one. Used badly, it is a very expensive way to get the same answer three times. This issue is the config to run your first team, plus the rule for when a team is worth it.

The short version: parallelize work that is genuinely independent, keep a single agent for work that is one decision deep.

The Blueprint

Three pieces get you a working team: one flag, one subagent file, one kickoff prompt. Copy, paste, customize.

Step 1: turn teams on. Agent Teams is experimental and disabled by default. Add the flag to ~/.claude/settings.json so it persists across projects. You need Claude Code v2.1.32 or later and an Opus 4.6+ model on the team lead.

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

Step 2: define a teammate. Subagents are markdown files with YAML frontmatter. Project agents live in .claude/agents/, personal ones in ~/.claude/agents/. The two fields that matter most are description (the team lead reads this to decide when to call the agent) and model (this is your main cost lever). Save this as .claude/agents/researcher.md:

---
name: researcher
description: Read-only fact finder. Use to map how existing code works and gather sources before any change is made.
tools: Read, Grep, Glob, WebSearch
model: haiku
---
You are a focused research agent. Given a question, gather evidence
from the codebase and the web. Return a tight summary: claims first,
then the file paths and URLs that back each claim. Do not edit files.
Do not speculate. If you cannot find something, say so plainly.

Note the model: haiku line. Research is read-heavy and cheap to verify, so it does not need your most expensive model. Reserve Opus for the work that writes code and makes judgment calls.

Step 3: kick off the team. You do not script the orchestration. You describe the team in plain language and the lead builds it. Paste this into a Claude Code session:

Create an agent team for this task.
You are the team lead: coordinate and synthesize, do not write code yourself.

Spawn three teammates:
1. researcher  - map how our current auth flow works and report back
2. implementer - add refresh-token rotation, only after researcher reports
3. reviewer    - read the implementer's diff, flag bugs and missing tests

Run them in that order. Researcher and reviewer are read-only.
Report the plan back to me before anyone commits.

That is a real team doing real work. The lead reads each description, assigns the task, and hands results between teammates. You approve the plan before anything lands.

The Anvil

Now the part the demos skip: where teams break, and how to stop the bleeding.

The fan-out tax is real. Every teammate is a separate context window burning separate tokens. Three agents on a parallel task can be worth it. Three agents passing one decision back and forth in sequence is just one agent with extra invoices. Before you spawn, ask one question: are these tasks independent? If the answer is "no, B needs A's output," you may not need a team at all, you need one agent working in order.

Permission prompts will stall a team. When five teammates each pause to ask "can I read this file," the lead grinds to a halt waiting on you. Pre-approve the safe, common operations before you spawn anything. Drop this in your project settings.json:

{
  "permissions": {
    "allow": [
      "Read",
      "Grep",
      "Glob",
      "Bash(npm test:*)",
      "Bash(git diff:*)"
    ]
  }
}

Keep writes and destructive commands off the allow list on purpose. You want the team to read freely and ask before it changes anything.

Read-only teammates are your seatbelt. Give research and review agents read tools only (Read, Grep, Glob, WebSearch). One writer per team is plenty. Two agents editing the same files in parallel is how you get merge conflicts an agent then confidently resolves wrong.

The rule of thumb: match the model to the job, not the prestige of the task. Haiku for reading and reporting, Sonnet for routine edits, Opus for the lead and for anything load-bearing. A team where every agent runs Opus is the fastest way to a bill that makes you turn the feature off.

Sparks

A few more things worth your attention this week:

Agent Teams requires Opus 4.6+ on the lead and Claude Code v2.1.32+. If the flag does nothing, check your version first with claude --version.
The same subagent files power single-agent delegation too. You do not need teams turned on to get value from a good .claude/agents/ folder. Start there if you are not ready for parallel runs.
The MCP spec release candidate (dated 2026-07-28) makes the protocol stateless at the core, so remote MCP servers can sit behind a plain load balancer. Worth a look if you run your own servers.
MCP Apps are now official: a tool can return HTML that renders as an interactive UI inside the chat. We will build one in a future issue.

The Smith's Take

The multi-agent hype cycle wants you to believe more agents is more better. It is not. More agents is more parallelism, and parallelism only helps when the work actually splits.

The builders who win with Agent Teams are not the ones spawning 70 agents for the screenshot. They are the ones who looked at a task, saw three genuinely independent chunks, and ran three agents instead of waiting through three serial passes. That is the whole game: find the independent work, hand it out, keep one writer, match the model to the job.

Turn the flag on. Write one researcher.md. Run one small team on a task you already understand, so you can tell whether it actually helped. Then decide. Make one work first, then scale.

Ship agents that actually work.

Michael