Model routing for subagents: let Haiku do the chores, Opus the hard parts

After using Claude Code for a while, you notice most tokens aren’t spent on “thinking” but on reading: scanning files, grepping, reading logs, listing call sites. Sending that work to the strongest model is wasteful. Subagents let you split it off, run it in a separate context on a cheaper model, and keep the big model focused on design, decisions and review.

What is a subagent?

A subagent is a specialised AI assistant inside a Claude Code session. Each one has:

• Its own context window — verbose output (search results, logs, file contents) stays out of the main conversation; the subagent returns only a condensed result.
• Its own system prompt — focused on a single role.
• Its own tools and permissions — read-only, for example.
• Its own model — the key to saving money.

Note: subagent requests still count toward the same usage limits as your main session. The saving comes from cheaper models and a lean main context — it isn’t “free”.

Built-in subagents

Explore and Plan skip CLAUDE.md files and the git status snapshot to stay fast and cheap.

Creating your own subagent

The quickest way: describe the subagent to Claude and say where to save it — Claude writes the file. Or create a Markdown file yourself:

---
name: code-scout
description: Find files, read logs, list where a function is used. Use proactively when surveying the codebase.
tools: Read, Glob, Grep
model: haiku
---
You are a code-survey assistant. Read only, never edit.
Return a list of files + relevant line numbers, at most 20 items,
each with one sentence on why it matters.

The frontmatter (YAML between the --- markers) is the configuration; the Markdown body becomes the subagent’s system prompt. Only name and description are required.

Where to save it

When names collide, the higher-priority location wins. Claude Code watches these folders, so edits take effect within seconds without a restart.

Frontmatter fields worth using

How Claude picks a subagent’s model

1. The model parameter Claude passes when invoking the subagent (if any).
2. The model frontmatter field (inherit = the main session’s model).
3. The CLAUDE_CODE_SUBAGENT_MODEL environment variable.
4. The main session’s model.

To force every subagent onto one model (for instance to cap a whole team’s costs), set both variables in settings.json:

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

With FORCE on, the frontmatter model field is ignored (requires Claude Code v2.1.257 or later). Run /tasks to see which model a running subagent is using.

Suggested role-to-model mapping

Invoking subagents

• Automatically: Claude matches your request against each description. Add “use proactively” to encourage delegation.
• In plain words: “Use the code-scout subagent to find every call to createOrder.”
• @-mention: type @ and pick the subagent — guarantees that one runs.
• Whole session: claude --agent code-scout gives the main session that subagent’s tools and model.
• Ad hoc via CLI: claude --agents '{...JSON...}' — lives only for the session, nothing written to disk.

Limits to know

• By default up to 20 subagents run concurrently, nested at most 3 levels below the main session.
• A subagent starts with a fresh context: it doesn’t see your conversation history. Restate important rules in the delegation prompt.
• A new subagent needs time to gather context — for small, back-and-forth tasks, staying in the main session is faster.

How to apply it

• Developers: Create 2–3 daily subagents: code-scout (haiku, read-only), test-runner (haiku/sonnet, runs and summarises tests), reviewer (opus, read-only). Watch your usage for a week to see the difference.
• Tech Leads: Commit .claude/agents/ to the repo so the whole team shares the same roles — like sharing a linter config.
• PMs: When the team complains about running out of Claude Code quota mid-week, routing subagent models is one of the cheapest ways to stretch limits before upgrading plans.