Subagents use too many tokens: how do you give them a cheaper model?
In Claude Code, write model: haiku at the top of the subagent file. In Codex, set default_subagent_model under [agents] in ~/.codex/config.toml. Each subagent runs its own requests against the same allowance, so searching, reading files and similar simple work is cheapest on a small model.
Codex
Set default_subagent_model under [agents] in ~/.codex/config.toml, and every subagent uses the smaller model by default.
Without configuration, a subagent inherits the model and reasoning effort of the main session. Set a default for all of them under [agents] in config.toml, or give one subagent its own .toml file with model and model_reasoning_effort; the file takes precedence over the default. OpenAI suggests GPT-5.6 Terra for searching, reading large files and processing material, and GPT-5.6 Luna for well-defined, repetitive work. To limit how many run at once, set max_concurrent_threads_per_session under [agents].
What the official docs say
Because each subagent does its own model and tool work, subagent workflows consume more tokens than comparable single-agent runs.If you don't configure a subagent model or model_reasoning_effort, the subagent inherits the parent agent's model and reasoning effort.To balance intelligence, speed, and price for each task, request a specific model or reasoning effort in your prompt, configure [agents] defaults in config.toml, or set model and model_reasoning_effort directly in the custom agent file.Use gpt-5.6-terra when you want a faster, lower-cost option for lighter subagent work.If a custom agent file sets model or model_reasoning_effort, the value in the file takes precedence.Claude
Write model: haiku at the top of the subagent file. To change all of them at once, set the CLAUDE_CODE_SUBAGENT_MODEL environment variable.
The /usage panel gives the reason: "Each subagent runs its own requests. Be deliberate about spawning them — and consider configuring a cheaper model for simpler subagents." Subagent files live in .claude/agents/ (this project) or ~/.claude/agents/ (all projects). The model field at the top takes haiku, sonnet, opus, fable, a full model ID or inherit; leave it out and the subagent uses the main session model. CLAUDE_CODE_SUBAGENT_MODEL sets a default for all subagents, but only a default: a model written in the file, or one Claude names when it delegates, comes first. While a subagent runs, /tasks shows which model it is on.
What the official docs say
For simple subagent tasks, specify model: haiku in your subagent configuration.CLAUDE_CODE_SUBAGENT_MODEL is a default, so a subagent's definition or a model Claude passes still takes precedence over it. To apply one model to every subagent, teammate, and workflow agent, also set CLAUDE_CODE_SUBAGENT_MODEL_FORCE to 1.A user or project subagent named Explore overrides the built-in and keeps its own model field, so define one with model: haiku to keep exploration on a lower-cost model.Agent teams use approximately 7x more tokens than standard sessions when teammates run in plan mode, because each teammate maintains its own context window and runs as a separate Claude instance.A single burst of heavy activity, such as a large workflow fanout, can exhaust the weekly allowance before the session window resets.Codex: what to write
Default for every subagent: in ~/.codex/config.toml, under [agents], add default_subagent_model = "gpt-5.6-terra" and default_subagent_reasoning_effort = "medium".
One subagent only: create a .toml file in .codex/agents/ (this project) or ~/.codex/agents/ (all projects). Three fields are required: name, description and developer_instructions. Then add model and model_reasoning_effort. The official example, pr-explorer.toml, sets name = "pr_explorer", model = "gpt-5.6-luna" and model_reasoning_effort = "medium".
Order of precedence: a model named when the subagent is spawned, then the [agents] default, then the main session model. A value in the agent file takes precedence over the default.
Claude Code: what to write
One subagent: create log-reader.md in .claude/agents/. Between the two --- lines at the top, write three lines. First, name: log-reader. Second, description: Reads logs and runs tests, reports failures only. Third, model: haiku. Below that, write its instructions, for example: Report only the failing tests and their errors. Do not paste the full output.
All subagents: in the env block of settings.json, add "CLAUDE_CODE_SUBAGENT_MODEL": "haiku". To apply it to every subagent with no exceptions, also add "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1" (requires v2.1.257 or later).
Only the built-in Explore: create your own subagent named Explore with model: haiku. It overrides the built-in one.
Order of precedence: the model named when the task is delegated, then model in the subagent file, then CLAUDE_CODE_SUBAGENT_MODEL, then the main session model.
Common misconceptions
- Subagents have their own allowance, so running many in parallel does not touch the main session
They do not. Subagents, agent teams and parallel cloud tasks all draw from the same 5-hour and weekly limits. Running them in parallel only spends those limits faster.
- Once CLAUDE_CODE_SUBAGENT_MODEL is set, every subagent is on the small model
Not quite. It is only a default: a model written in the subagent file, or one Claude names when it delegates, comes first, and the built-in Explore and Plan are not affected. To force all of them, also set CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1, then confirm with /tasks.
- Handing work to a subagent saves tokens
Not necessarily. A subagent saves context in the main session: the long output stays on its side and the main session gets a summary. But it has to read the background from scratch, so the total is often higher. Hand over work with long, messy output (running tests, fetching docs, reading logs), and it pays off only with a small model.
Tips
- Start with the subagent you run most. /usage in Claude Code lists which subagent uses the most; changing that one pays off fastest.
- Give searching, reading files, running tests and reading logs to a small model. Keep decisions (architecture, hard bugs) on the main session model.
- Run fewer. Claude agent teams use about 7x the tokens of a standard session, and one large fanout can use up the weekly limit before the 5-hour limit resets.
- When you delegate, state the scope and what to report back, for example "report only failing tests and their errors". For a subagent you run often, the /usage panel suggests exactly that: a smaller model or a tighter prompt.
- Shut them down when done. A teammate that has not exited keeps using tokens.
- In Codex you can also name the model in the prompt: "use gpt-5.6-terra at medium for this subagent". A model named at spawn takes precedence over the default.
- A Claude Code subagent can also set its own effort (low, medium, high and up), in the same place as model.