How to Set Which Model Claude Code Subagents Use

In Claude Code, a subagent is a separate agent that handles a task, such as reviewing code or exploring a codebase. Its model is the Claude model that generates its responses. To choose that model, set model in the subagent’s definition, pass a model when Claude Code invokes the agent, or configure an environment variable as a default or broad override.

Set the custom subagent’s model field to choose its model. CLAUDE_CODE_SUBAGENT_MODEL provides a fallback for subagents; add CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 to enforce that model across them. Claude Code's version affects which setting takes precedence. When you need to confirm which model an agent used, check it with /tasks. The Claude Code subagent documentation describes these settings and their exceptions.

Set a model in the subagent definition

A subagent definition is a Markdown file with YAML frontmatter. YAML frontmatter is the block of settings at the top of the file. Add model there to give that agent a default:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

Review the relevant code and provide specific, actionable feedback.

Choose a supported alias such as sonnet, opus, haiku, or fable, or enter the full model ID; your account and configuration must have access to it. Save a project-specific definition under .claude/agents/ to share it with the project. To use a definition across projects on that machine, save it under ~/.claude/agents/.

Set model: inherit when you want the subagent to use the same model as the main Claude Code conversation. This explicitly tells Claude Code to use the main conversation’s model. If you leave out model, Claude Code continues through its model-selection rules.

Choose a model for one invocation

When Claude Code calls the Agent tool, it can pass a model parameter. That choice applies to that call and takes precedence over the model in the subagent’s definition. The documented parameter accepts the aliases sonnet, opus, haiku, and fable; it does not accept a full model ID or inherit.

Use this option to run the same subagent with different models for different tasks. To apply a model assignment consistently, configure the definition or use the force setting. Asking for a model in ordinary prompt text does not guarantee that Claude Code will pass the Agent tool’s model parameter.

Use an environment variable as a default or override

Set CLAUDE_CODE_SUBAGENT_MODEL to specify a fallback model for subagents. The documented selection order gives precedence to the model passed for an individual call and the subagent’s model field; Claude Code uses this environment variable if neither choice assigns a model. If the variable does not assign one, or if you set it to inherit, Claude Code uses the main conversation’s model.

To override subagent definitions and invocation-level choices broadly, set CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 as well. Anthropic documents this force behavior for Claude Code v2.1.257 and later. For example, add both variables to the env section of the relevant settings file:

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

The user settings file, ~/.claude/settings.json, applies to your configuration. A project can share settings with contributors through .claude/settings.json. Claude Code’s settings documentation lists the available settings locations.

Set both variables to force a specific model. The force variable alone does not choose a model. If CLAUDE_CODE_SUBAGENT_MODEL is unset, subagents use the main conversation’s model, except for the built-in Explore subagent. Forks and skills that run as subagents with model: inherit also use the main conversation’s model.

Check which model Claude Code used

While the subagent is active, run /tasks to see which model it used. The model display requires Claude Code v2.1.242 or later. If an organization’s model allowlist blocks the requested model, Claude Code can use an allowed model instead and warn you during an interactive session. Check the /tasks entry and any warning to confirm which model ran.

Explore and Plan generally inherit the main conversation’s model, and setting CLAUDE_CODE_SUBAGENT_MODEL alone does not change that. A user- or project-defined subagent named Explore can replace the built-in agent and specify its own model. Claude Code assigns other helper agents specific models too, so check their documented behavior rather than assuming they follow the same rule.

Follow the version-specific precedence

For a normal subagent, Claude Code checks these model choices in order:

The environment variable’s position changed in Claude Code v2.1.251. Before that version, CLAUDE_CODE_SUBAGENT_MODEL took precedence over the model passed for an invocation and the one in the subagent’s frontmatter. Older instructions that call it an unconditional override may describe that earlier behavior. In current versions, also set the force variable to override those choices.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com