# How to run multiple agents in Claude Code

AutoRouter · Oct 23, 2026 · Updated Oct 27, 2026 · 6 min read

Claude Code has two multi-agent features inside a session. Subagents each work in their own context window and return only a summary to the main conversation, and agent teams, which are experimental and off by default, let a lead session coordinate teammates that share a task list and message each other, according to Anthropic's subagent and agent team docs (checked October 26, 2026). Each agent sends its own requests, so the model it runs on decides most of what multi-agent work costs. AutoRouter, the Mac app for Codex and Claude Code adds 20+ models to Claude Code's /model picker and can pick a model for each turn.

AutoRouter wrote this post. Everything about Claude Code comes from Anthropic's documentation, linked where it is used.

## What are Claude Code's multi-agent options?

Claude Code's multi-agent options differ in who coordinates the work and how much context each agent carries. Subagents suit focused side tasks whose result is all you need; agent teams suit work where agents need to share findings and challenge each other.

For sessions you run yourself in parallel, Claude Code also has background agents and cross-session messaging, which sit outside a single session.

## How do Claude Code subagents work?

A subagent is a specialized assistant with its own system prompt, tool access and permissions that Claude delegates to when a task matches its description. Claude Code ships with built-in subagents: Explore, a fast read-only agent for searching code; Plan, a read-only research agent used during plan mode; and a general-purpose agent for multi-step work that needs both exploring and editing.

You define your own as a Markdown file with YAML frontmatter, in .claude/agents/ for one project or ~/.claude/agents/ for every project on your machine. Only name and description are required:

```markdown
---
name: test-runner
description: Runs the test suite and reports failures. Use after code changes.
tools: Read, Grep, Glob, Bash
model: haiku
---

Run the tests, then list each failure with its file, line and a one-line cause.
```

Keep descriptions short, because Claude reads all of them to decide when to delegate. Claude Code warns at startup when your subagents' combined descriptions pass 15,000 tokens.

## How do agent teams work?

An agent team is a lead session that spawns teammates, assigns tasks from a shared list, and combines their results, while you can talk to any teammate directly. Enable it in your settings, then ask for a team in plain language, such as "Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for each teammate" (docs):

```json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
```

Anthropic suggests starting with three to five teammates and five or six tasks per teammate (best practices). Teams have limits worth knowing before you rely on them:

• - One team per session, and teammates can't spawn teammates of their own.
• - /resume and /rewind don't restore in-process teammates.
• - Teammates only spawn in interactive sessions; with claude -p a named subagent runs as an ordinary subagent.
• - Split panes need tmux or iTerm2; the default in-process mode works in any terminal.

## Which model does each agent use?

Each agent takes its model from the first source that sets one. For a subagent, the order is the model Claude passes when it starts the subagent, then the model field in its frontmatter, then the CLAUDE_CODE_SUBAGENT_MODEL variable, then the main conversation's model. For a teammate, the order is the model your spawn prompt names, then its subagent definition's model, then CLAUDE_CODE_SUBAGENT_MODEL, then the lead's model.

CLAUDE_CODE_SUBAGENT_MODEL is only a default. To put every subagent and teammate on one model, also set CLAUDE_CODE_SUBAGENT_MODEL_FORCE (Claude Code v2.1.257 or later):

```json
{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}
```

Run /tasks while a subagent works to see the model on its row (v2.1.242 or later). Every way to choose a model in Claude Code works through a full example of which model each subagent ends up on.

## How much do multiple agents cost?

Multiple agents cost more because each one sends its own requests, and subagent requests "count toward the same usage limits" as the main conversation, per the docs. Anthropic's cost guide puts agent teams at about seven times the tokens of a standard session when teammates run in plan mode, and the team docs say token costs scale linearly with the number of teammates.

Caching changes too. A teammate's prompt cache holds for five minutes by default, including on a Claude subscription; set subagentPromptCacheTtl to 1h to keep it longer, which the API bills at a higher write rate (docs).

The cheapest lever is the model. Anthropic lists "routing tasks to faster, lower-cost models like Haiku" as one reason to use subagents at all. Give search, test runs and log reading a smaller model, and keep the strongest model for the work that needs judgment. How Claude Code usage limits work covers the five-hour window and weekly cap that all of these requests draw from.

## Where does AutoRouter fit?

AutoRouter picks a model for each turn in the main conversation while it is the model selected in /model, using the same idea as giving each agent a model that fits its work. Your own rules decide a turn first. Otherwise hard work goes to the most capable model your plans cover, and everything else goes to the model that costs you least among those that clear the quality bar for it.

In Claude Code, Claude models run on your Claude plan, and AutoRouter adds 20+ models from other providers to the picker. Every turn shows its model, what it cost and why. Picking a specific model in /model sends turns straight to it, because AutoRouter routes only while it is the model selected. How AutoRouter picks a model for each turn covers the full order. AutoRouter is in beta and runs on macOS 14 or later; Claude Code needs Node 22.18 or later.

## Questions

### Do subagents count against my Claude plan limits?

Yes. Each subagent sends its own requests, which count toward the same usage limits as your main conversation, according to the subagent docs. A subagent can still save usage by keeping long search results out of the main conversation's context.

### Why did Claude start teammates when I wanted a subagent?

With agent teams enabled, a subagent that Claude names when it spawns it launches as a teammate, so a team can form even when you didn't ask for one. The troubleshooting section explains how to turn that behavior off.

### How do I see which model a subagent is using?

Run /tasks while the subagent is running. Claude Code names the model on the subagent's row, along with any effort level set for it, on version 2.1.242 or later.

### Can I run a subagent on a cheaper model?

Yes. Set model: haiku, or another alias or full model ID, in the subagent's frontmatter. To move the built-in Explore subagent too, define your own subagent named Explore with its own model field, or force one model onto every subagent with CLAUDE_CODE_SUBAGENT_MODEL_FORCE.

## Sources

• - Create custom subagents, checked October 26, 2026
• - Orchestrate teams of Claude Code sessions, checked October 26, 2026
• - Manage costs effectively, checked October 26, 2026
• - Background agents, checked October 26, 2026
• - Cross-session messaging, checked October 26, 2026