Sulat.com / Writing on AISaturday, November 21, 2026
Agent Engineering/21 November 2026

Claude Code’s docs now list CLAUDE_CODE_SUBAGENT_EFFORT, a default effort level for subagents

Anthropic's Claude Code docs now list CLAUDE_CODE_SUBAGENT_EFFORT, a default effort level for subagents and workflow agents. Here's how it ranks against the other effort settings, how to set it and what it skips.

Glossy orange Claude starburst beside a steel dial and five small orange cubes with their own dials turned low

At a glance

  • Anthropic's Claude Code docs now list CLAUDE_CODE_SUBAGENT_EFFORT, which sets the default effort level for subagents and workflow agents.
  • It takes low, medium, high, xhigh or max, and needs Claude Code v2.1.315 or later; the changelog logged it on 31 October in v2.1.316.
  • CLAUDE_CODE_EFFORT_LEVEL, an effort passed at spawn and an effort field in the subagent file all beat it; the session level applies only when none of them is set.
  • Forks, forked skills and teammates ignore the variable.
  • Set it in the shell or in the env block of a settings file.

Anthropic’s Claude Code documentation now lists CLAUDE_CODE_SUBAGENT_EFFORT, an environment variable that sets the default effort level for subagents and workflow agents. A subagent on the same model as your session takes the session’s level unless something else names one, so a session at xhigh sends every subagent out at xhigh too. The changelog logged the variable on 31 October under version 2.1.316, and the environment variables page says it needs Claude Code v2.1.315 or later.

What the variable does

Its row on the page reads: “The default effort level for subagents and workflow agents: low, medium, high, xhigh, or max. It doesn’t apply to forks, forked skills, or teammates.” Which of those five levels you get depends on the model. If you set one the active model doesn’t support, Claude Code drops to the highest level it does support at or below your pick, so xhigh runs as high on Opus 4.6.

The default matters most if you’ve raised your own level. Fable 5.2, Opus 5.5, Sonnet 5.5 and Haiku 5.5 all start at medium in Claude Code, and Anthropic’s model configuration page says lower effort is “faster and cheaper for straightforward tasks, while higher effort provides deeper reasoning for complex problems.” The pages describe the variable as an effort default and don’t mention the 5-hour or weekly usage limits.

Two rows: a session at xhigh with three xhigh subagents, then the same session with three subagents set to low
Set the variable and subagents stop copying the session’s level.

Which setting wins

The subagents page sets the order. The CLAUDE_CODE_EFFORT_LEVEL variable beats everything, including the effort Claude can pass when it spawns a subagent (v2.1.292 or later) and the effort field in the subagent’s own file. The per-call parameter beats the field. For a subagent with neither, the page lists what applies, first match wins:

  1. CLAUDE_CODE_EFFORT_LEVEL, if you set it.
  2. The effort set for the subagent that spawned it, or a level set only for the current turn, such as a skill’s effort.
  3. CLAUDE_CODE_SUBAGENT_EFFORT, if you set it.

With none of those, a subagent on the main conversation’s model runs at the level you pick with /effort or --effort. A subagent on a different model doesn’t take the session level at all, and the docs say to set its effort field instead.

Six-step ladder of effort sources for a subagent, with CLAUDE_CODE_SUBAGENT_EFFORT fifth, above the session level
The new variable only applies when nothing above it names a level.

How to set it

Check you’re on v2.1.315 or later with claude --version, then export the variable in the shell that starts Claude Code:

export CLAUDE_CODE_SUBAGENT_EFFORT=low
claude

To apply it to every session, put it in the env block of a settings file such as ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_EFFORT": "low"
  }
}

Claude Code reads shell variables at startup, while env entries in settings files are reapplied to a running session when the file changes. If the same variable is in both places, the settings file value applies in most sessions.

The variable is a default for agents that don’t say otherwise, and a single agent can still pin its own level. A review subagent that should keep thinking hard sets the field in its definition:

---
name: reviewer
description: Reviews a diff for bugs and missing tests
tools: Read, Grep, Glob
effort: high
---

What it leaves alone

Forks, forked skills and teammates ignore the variable. A fork is a subagent that inherits the entire conversation so far, and teammates are the members of an agent team. Other subagents and workflow agents pick it up.

The variable covers subagents and workflow agents, and skips forks, forked skills and teammates
Forks, forked skills and teammates ignore the variable.

Discover more from Sulat AI & Tech News

Subscribe to get the latest posts sent to your email.