D12 · Agent teams & dynamic workflows

This lesson lays out the two advanced routes to multi-agent collaboration: what an agent team is, how it differs from subagents, and how to start one; how a dynamic workflow orchestrates subagents at scale deterministically from a script; and — most importantly — when orchestration is worth it, and when a single session is actually the cheapest option.

Why this lesson comes today

D10's subagents solved "delegating work inside one session": each worker has its own context, but can only report results back to the main agent — workers never talk to each other. D11's worktrees solved "manually running several parallel sessions": physical isolation, but you have to be the coordinator. That leaves two gaps: first, workers can't discuss or challenge each other's conclusions; second, the "do this first, then that" orchestration logic exists only in Claude's context at that moment — switch sessions and it's gone, unreproducible.

Our takeD12's two mechanisms fill exactly those gaps: agent teams let multiple full sessions share a task list and message each other; workflows turn the orchestration itself into a readable, storable, re-runnable script. After this lesson you'll hold the complete spectrum of tools from "one session" to "hundreds of agents". D13 (Headless & CI) will build on today's conclusions: workflows run just as well under claude -p and the Agent SDK, making them the foundation of automated pipelines; and a saved workflow can be packed into a plugin for distribution — that's D14.

Core concepts, explained

Agent team: a squad of full sessions that talk to each other

OfficialAn agent team is multiple Claude Code instances working together: your main session acts as the team lead, coordinating, assigning tasks, and aggregating results; each teammate is a complete, independent Claude Code session with its own context window, and teammates can message each other directly — you can also bypass the lead and talk to any teammate yourself. A team consists of four parts: the team lead (coordination), teammates (doing the work), a shared task list (claiming work), and a mailbox (inter-agent messaging, one JSON inbox file per agent).

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

OfficialStarting one takes no ceremony: with the flag on, describe the task and the teammates you want in natural language, and Claude spawns the teammates, populates the shared task list, and starts coordinating (since v2.1.178 there is no separate "create a team" step; the old TeamCreate/TeamDelete tools were removed). Claude may also proactively propose a team when it judges a task fit for parallel work, but nothing is spawned without your confirmation. A few mechanics worth remembering:

• Task list: tasks have three states — pending / in progress / completed — and can declare dependencies; claiming uses a file lock so two teammates can't grab the same task. The lead can assign tasks by name, and teammates can pick up the next task themselves when they finish one.
• Reusing roles: when spawning teammates you can directly reference a subagent type defined in D10 (such as security-reviewer); the teammate honors that definition's tools allowlist and model, and the definition body is appended to the teammate's system prompt.
• Permissions: teammates inherit the lead's permission settings, and permission prompts bubble up to the lead session for you to approve in person; one teammate can't authorize on your behalf, nor hand a denied operation to another teammate to sneak past the check.
• Quality gates: combined with D8's hooks, the TeammateIdle / TaskCreated / TaskCompleted hooks block with exit code 2 — enough to send a teammate back to work when it tries to clock out early.
• Display modes: the default is in-process (all teammates in one terminal; arrow keys to pick one, Enter to enter its conversation); to see everyone on one screen use split panes (requires tmux or iTerm2), switched via the teammateMode setting.

Versus subagents: do the workers need to talk?

OfficialBoth can work in parallel; the dividing line is whether workers need to communicate with each other:

OfficialThe strong use cases the docs give: parallel code review (one reviewer each for security / performance / test coverage), competing-hypothesis debugging (several teammates each champion one bug hypothesis and debate to knock the others down — the theory left standing is more likely the real root cause), and cross-layer collaboration (frontend / backend / tests each owning a lane). Conversely, sequential tasks, work that touches the same files, and long dependency chains are better served by a single session or subagents.

Dynamic workflow: moving orchestration out of context, into code

OfficialA dynamic workflow is a JavaScript script that orchestrates subagents: you describe the task, Claude writes the script for you, and a runtime independent of the session executes it in the background. The key design point: intermediate results live in script variables, not in Claude's context window — the session only receives the final answer. Who holds the plan changes too: with subagents, skills, and agent teams, Claude decides the next step turn by turn; with a workflow, the script holds the loops, branches, and intermediate results, so the same orchestration can be re-run as-is. Requires Claude Code v2.1.154+, available on paid plans; Pro users flip the Dynamic workflows toggle in /config.

OfficialThere are three ways to start one:

1. Ask for it in the prompt: write the keyword ultracode, or simply say "use a workflow for this" in natural language, and Claude writes a script for the task instead of working turn by turn.
2. Let Claude decide: /effort ultracode (xhigh reasoning + automatic orchestration) — after that, Claude plans every substantial task as a workflow; token consumption rises noticeably, and it lasts only for the current session.
3. Run a ready-made command: the built-in /deep-research (multi-angle search, cross-verification, a report with citations), or any workflow command you've saved yourself.

OfficialA saved script looks like this (a meta block plus a script body with top-level await):

export const meta = {
  name: 'audit-routes',
  description: 'Audit every route handler for missing auth checks',
}

const found = await agent('List every .ts file under src/routes/.', {
  schema: { type: 'object', required: ['files'],
    properties: { files: { type: 'array', items: { type: 'string' } } } },
})

const audits = await pipeline(found.files, file =>
  agent(`Audit ${file} for missing authentication checks.`, { label: file }),
)

return audits.filter(Boolean)

Officialagent() launches one subagent (pass schema for structured results, label to name it in the progress view); pipeline() runs one agent per item in a list. An agent() call you stop midway, or that hits an unrecoverable API error, resolves to null, and pipeline() keeps the null in its result array — which is why the example ends with .filter(Boolean) to clear them out. The docs present only these two primitives; for the full options they point to the Workflow tool entry in the Agent SDK reference. Run progress appears in the /workflows view grouped by phase: agent count, total tokens, and elapsed time per phase, and you can drill all the way down to a single agent's prompt and result.

OfficialHard runtime constraints: at most 16 concurrent agents (fewer on machines with fewer CPU cores), a cap of 1,000 agents per run, no user input while a run is in progress (if a phase boundary needs human sign-off, split the work into multiple workflows), and the script itself cannot touch the filesystem or shell — all reads, writes, and commands are executed by agents; the script only coordinates. On permissions, workflow-spawned subagents always run in acceptEdits mode and inherit your tool allowlist; shell commands and web fetches outside the allowlist still pause for confirmation mid-run, so add the commands you'll need to the allowlist before kicking off a long run. A stopped run can be resumed within the same session: completed agents usually replay their cached results — a script fanned out into many small agents preserves far more progress than one long agent.

OfficialOnce a run produces results you like, select it in /workflows and press s to save: to the project's .claude/workflows/ (shared with the repo) or ~/.claude/workflows/ (yours only, available in all projects). It then becomes a /<name> command, and can take arguments passed at invocation via args (read inside the script as the global variable args). To distribute across teams, put it in a plugin's workflows/ directory and invoke it as /plugin-name:workflow-name.

Choosing among the four: who holds the plan?

OfficialThe docs give a master comparison table; the core axes are "who decides the next step" and "where intermediate results live":

Our takeOne-line selector: you only want the result, not the process → subagent; workers need to discuss and challenge each other → agent team; large scale, fixed steps, will run again later → workflow; what you want to capture is the "method", not the orchestration → skill (D7).

Cost awareness: when orchestration is worth it

OfficialBoth mechanisms cost far more than a single session, and the docs give explicit guardrails. Agent teams: token consumption grows linearly with teammate count; start with 3–5 teammates, with 5–6 tasks per teammate as the saturation point; three focused teammates often beat five scattered ones; beginners should start with non-coding tasks like research and review; two teammates editing the same file will overwrite each other, so split work along clean file boundaries. Workflows: trial-run on a small slice first to estimate cost (one directory, not the whole repo); when a single run schedules more than 25 agents, or is projected to exceed 1.5M tokens, the task panel shows a Large workflow warning (v2.1.203+, advisory only, doesn't block); the size guideline in /config controls the agent scale Claude aims for when writing scripts, defaulting to medium (up to 15, v2.1.219+); each agent defaults to the session's current model — you can have the script route lighter phases to a smaller model, or override globally with CLAUDE_CODE_SUBAGENT_MODEL — so glance at /model before a large run.

Hands-on: doable today

Prerequisite check: claude --version must be ≥ 2.1.154 (latest today is 2.1.222); on the Pro plan, first enable Dynamic workflows in /config. Steps 1–3 take about 30 minutes; step 4 is optional.

1. Try a built-in workflow. In a session, run /deep-research with a question you genuinely want answered — for example the one below. Expected: Claude Code asks whether to allow the workflow; after you choose Yes, the run moves to the background and a one-line progress summary appears in the task panel below the input box.

   /deep-research What changed in Node.js's permission model from v20 to v22?

2. Drill into the progress view. Run /workflows, select the run with the arrow keys, and press Enter. Expected: a view grouped by phase, each with agent count, total tokens, and elapsed time; keep pressing Enter to drill into a single agent and read its prompt, recent tool calls, and result. When it finishes, a report with citations lands back in the session, with conclusions that failed cross-verification filtered out.
3. Write and save your own workflow. Pick a small directory (cost awareness: small slices first) and ask, in natural language, for an audit workflow with adversarial verification. Expected: the approval prompt lists the planned phases, with an optional View raw script (or Ctrl+G to open in an editor) so you can read the script before letting it run; when it's done, press s in /workflows to save it, Tab to switch between the project / personal locations — and from then on it's one of your slash commands.

   Use a workflow to audit every route file under src/routes/ for missing auth checks.
   Have an independent agent adversarially verify each finding before it goes in the report,
   then summarize everything into one list sorted by severity.

4. (Optional) Spin up your first agent team. Add CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 to the env block of settings.json, restart the session, and send the prompt below. Expected: three teammates appear in the agent panel below the input box; arrow keys select one, Enter drops you into its session for a direct conversation; when they're done, have the lead merge the three reviews. Note: agents showing up in the panel doesn't mean you got a team (subagents share the same panel) — if Claude used subagents, explicitly ask again for an agent team.

   Spawn three teammates to review this PR in parallel:
   - one looks only at security risks
   - one looks only at performance impact
   - one looks only at test coverage
   Have each review independently and report back to you, then merge their findings into one review.

How to know you've learned it

• You can explain, without notes, how subagents, agent teams, and workflows differ on "who decides the next step" and "where intermediate results live", with one fitting use case for each.
• You've completed a /deep-research run and drilled down to an individual agent's prompt and result in the /workflows view.
• You've had Claude write a workflow from natural language, read the generated script (you can tell what meta / agent() / pipeline() / .filter(Boolean) each do), and saved it as your own slash command.
• You can name two cost guardrails: the thresholds that trigger the Large workflow warning, and the default size guideline tier.
• Self-test: you need to migrate 200 component files from styled-components to Tailwind — which mechanism, and why not an agent team? (Reference answer: a workflow — the files are independent of each other and workers don't need to talk, pipeline() fan-out is a natural fit, and the orchestration is savable, re-runnable, and resumable after interruption; an agent team's value lies in teammates communicating and challenging each other, which buys nothing here — you'd just pay coordination overhead and higher token cost.)