# How to run multiple agents in Claude Code Authors: AutoRouter Published: 2026-10-23T19:30:00.000Z Updated: 2026-10-27T01:40:00.000Z Reading time: 6 min Canonical: https://autorouter.com/blog/claude-code-multi-agent Publisher: AutoRouter, the Mac app for Codex and Claude Code (https://autorouter.com) > Claude Code runs multi-agent work in two ways inside a session: subagents, which work in their own context and report back to the main conversation, and agent teams, an experimental mode where a lead session coordinates teammates that share a task list and message each other. Every agent's requests count toward the same usage limits, so the model each agent runs on is the main cost lever. AutoRouter, the Mac app for Codex and Claude Code, picks a model for each turn in the main conversation. 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](https://code.claude.com/docs/en/sub-agents) and [agent team](https://code.claude.com/docs/en/agent-teams) 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](https://autorouter.com) 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. | | Subagents | Agent teams | | ------------ | ------------------------------------------------ | ---------------------------------------------------------- | | Status | On by default | Experimental; set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` | | Context | Own context window; results return to the caller | Own context window; fully independent | | Coordination | The main agent manages all work | Teammates message each other and share a task list | | Best for | Focused tasks where only the result matters | Research, review and features split across layers | | Token cost | Lower: results are summarized back | Higher: each teammate is a separate Claude instance | For sessions you run yourself in parallel, Claude Code also has [background agents](https://code.claude.com/docs/en/agent-view) and [cross-session messaging](https://code.claude.com/docs/en/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](https://code.claude.com/docs/en/sub-agents#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](https://code.claude.com/docs/en/agent-teams#specify-teammates-and-models)): ```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](https://code.claude.com/docs/en/agent-teams#choose-an-appropriate-team-size)). 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](https://code.claude.com/docs/en/sub-agents#choose-a-model) 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](https://code.claude.com/docs/en/agent-teams#specify-teammates-and-models) 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](/blog/claude-code-model-settings) 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](https://code.claude.com/docs/en/sub-agents). Anthropic's [cost guide](https://code.claude.com/docs/en/costs) 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](https://code.claude.com/docs/en/agent-teams#token-usage)). 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](/blog/claude-code-usage-limits) 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](/blog/how-autorouter-picks-a-model) 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](https://code.claude.com/docs/en/sub-agents). 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](https://code.claude.com/docs/en/agent-teams#claude-spawns-teammates-instead-of-subagents) 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](https://code.claude.com/docs/en/sub-agents), checked October 26, 2026 - [Orchestrate teams of Claude Code sessions](https://code.claude.com/docs/en/agent-teams), checked October 26, 2026 - [Manage costs effectively](https://code.claude.com/docs/en/costs), checked October 26, 2026 - [Background agents](https://code.claude.com/docs/en/agent-view), checked October 26, 2026 - [Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging), checked October 26, 2026 ## Read next - [How Claude Code plan mode works, and which model plans](https://autorouter.com/blog/claude-code-plan-mode.md): Claude Code plan mode has Claude read your code and propose a plan without editing any files until you approve it. Turn it on with Shift+Tab, by starting a prompt with /plan, or with claude --permission-mode plan. Planning runs on your session's model unless you pick opusplan, which plans on Opus and builds on Sonnet; AutoRouter, the Mac app for Codex and Claude Code, instead picks a model for each turn while it is selected. - [Try a new model in Codex or Claude Code without another API key](https://autorouter.com/blog/try-new-models-in-codex-and-claude-code.md): Every manual way to try a new model in Codex or Claude Code needs an API key: one per provider, or one gateway key such as OpenRouter's. Claude Code reaches another provider through environment variables, and Codex through a custom provider in config.toml. AutoRouter, the Mac app for Codex and Claude Code, adds 20+ models to both apps' model pickers with no keys or endpoints to set up, and new models show up there right away. - [Every way to choose a model in Claude Code](https://autorouter.com/blog/claude-code-model-settings.md): Claude Code takes its model from, in order of priority, the /model command, the --model flag, the ANTHROPIC_MODEL environment variable, the model key in settings.json and the ANTHROPIC_DEFAULT_MODEL variable. Aliases such as opus, sonnet, haiku, fable and opusplan stand for the current model in each family, and subagents take their model from their own model field, CLAUDE_CODE_SUBAGENT_MODEL or the main session. AutoRouter, the Mac app for Codex and Claude Code, adds one more choice to /model that picks a model for each turn while it is selected. Tags: [Claude Code](https://autorouter.com/blog/tags/claude-code.md), [Models](https://autorouter.com/blog/tags/models.md), [Guides](https://autorouter.com/blog/tags/guides.md) Drafted with AI from the sources linked above, then checked and edited by the AutoRouter team.