Force a consistent subagent model
CHANGELOG · original
Added CLAUDE_CODE_SUBAGENT_MODEL_FORCE to apply CLAUDE_CODE_SUBAGENT_MODEL (or the main model) to every subagent, ignoring per-spawn and agent-definition model overrides Open official changelog ↗ Documentation
Documentation excerpt
Run every subagent on one model
To apply one model to every subagent, teammate, and workflow agent, set CLAUDE_CODE_SUBAGENT_MODEL to that model and CLAUDE_CODE_SUBAGENT_MODEL_FORCE to 1. Requires Claude Code v2.1.257 or later.
For example, to run every subagent on Haiku, set both variables in the env block of a settings file:
{
"env": {
"CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
"CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
}
}
To check that the setting took effect, run /tasks while a subagent is running. The subagent's row shows the model it runs on.
While CLAUDE_CODE_SUBAGENT_MODEL_FORCE is on, Claude Code ignores the model field in subagent definitions, and Claude can't pass a model when it starts a subagent. The following subagents still run on their parent conversation's model:
- A fork
- A skill that runs in a subagent with
model: inherit
If you set only CLAUDE_CODE_SUBAGENT_MODEL_FORCE, subagents run on the main conversation's model, except that the built-in Explore subagent runs on the model listed for it under Built-in subagents.
Documentation snapshot · 2026-11-20