Model and Effort Configuration#

Claude Code exposes two orthogonal knobs for tuning every API call: which model to use and how much compute effort to spend per response. Both can be set globally or scoped to individual subagents, skills, or sessions. The authoritative reference is the Model configuration doc.

Model Selection#

Aliases and full model IDs#

The model setting accepts either a model alias or a full model name (e.g., claude-opus-4-8):

Aliases resolve to different specific versions depending on the provider (Anthropic API, Bedrock, Vertex, Foundry). Use a full model name to pin to a specific version 1.

Configuration priority (highest → lowest)#

1. CLAUDE_CODE_SUBAGENT_MODEL env var — overrides model for all subagents and agent teams 1
2. /model slash command — switches immediately; as of v2.1.153 saves as user default. Press s in the picker to switch for the current session only 1
3. --model CLI flag — applies to the launched session only 2
4. ANTHROPIC_MODEL env var — session-scoped override 1
5. model field in settings — persistent default in ~/.claude/settings.json or project settings 1
6. model frontmatter in subagent/skill — scoped to that agent or skill invocation 3

Alias resolution env vars#

To control what each alias maps to (e.g., on Bedrock or Vertex), use:

1

Enterprise model restrictions#

Admins can use availableModels in managed settings to restrict which models users can select in /model 1. The default option always remains available. Combine availableModels, model, and the alias env vars to fully control model routing.

Effort Level#

Effort controls adaptive reasoning — how much thinking the model applies per step. Higher effort → deeper reasoning, more tokens, higher cost.

Available levels#

Not all levels are available on every model — unsupported levels fall back to the nearest supported one 1.

Configuration priority (highest → lowest)#

1. CLAUDE_CODE_EFFORT_LEVEL env var — overrides all other methods 1
2. /effort slash command — interactive slider or effort <level> directly; /effort auto resets to model default 1
3. --effort CLI flag — session-scoped 2
4. effortLevel in settings — persistent; accepts low, medium, high, xhigh only (max and ultracode are session-only) 1
5. effort frontmatter in subagent/skill — overrides session effort while that agent is active, but not the env var 3
6. Model default — high on Opus 4.8/4.6/Sonnet 4.6; xhigh on Opus 4.7 1

The current effort level is shown next to the logo/spinner (e.g., "with low effort") without opening /model 1.

One-off overrides#

• ultrathink keyword in a prompt requests deeper reasoning for that turn without changing the session effort setting 1.
• The effort slider is also accessible within the /model picker using left/right arrow keys 1.

Subagent / Skill Frontmatter#

Both subagent and skill markdown files accept model and effort in their YAML frontmatter 3. The subagent's model field accepts inherit (default), sonnet, opus, haiku, or a full model ID 4. Model resolution order for subagents: CLAUDE_CODE_SUBAGENT_MODEL env var → per-invocation parameter → model frontmatter → parent session model 3.

Key References#

• Model configuration docs — full alias table, env vars, availableModels, extended context, opusplan
• Manage costs effectively — /usage, model: haiku for agents, /effort tuning
• Create custom subagents — model and effort frontmatter fields, resolution order
• Agent development SKILL.md — frontmatter schema for plugin agents
• CHANGELOG.md — per-version flag introductions (search CLAUDE_CODE_EFFORT_LEVEL, ANTHROPIC_MODEL)