Claude Code subagent effort: how to use the new setting

Claude Code now lets you pick the effort level your subagents run at, separate from your main session. Set CLAUDE_CODE_SUBAGENT_EFFORT=low (or medium, high and so on) before you start claude, or put it in the env block of your settings, and any subagent that doesn't name its own effort runs at that level instead of copying yours.

Where this came from on X

It started as a user question. On Wednesday night, @sam_commonly asked Boris Cherny, who leads Claude Code at Anthropic, "can subagents default to lower effort instead of inheriting it?"

On Thursday, @bcherny replied: "Just landed CLAUDE_CODE_SUBAGENT_EFFORT." He gave the one-line launch command and said you can also set it in your custom agent config. A minute later @CampbellKaleb23 quoted the reply and spelled out the problem it fixes: until now, "subagents naturally inherit the model effort you are using."

The setting is now in the public 2.1.316 release notes, dated October 31. That release describes the variable as setting "the effort level subagents run at when nothing else names one, instead of inheriting the session's."

Why inheriting effort was a problem

Effort controls how much the model thinks before it answers. Plenty of people run their main session at high or xhigh, because that's where planning and tricky edits happen. Before this change, every subagent Claude launched got the same level, even one sent to list files or grep a folder.

A search subagent thinking at xhigh is slower than it needs to be, and it burns usage you'd rather spend on the main thread. On a capped plan, that can be what pushes you into a limit halfway through a task.

How to set it

The subagent docs list low, medium, high, xhigh and max as options and note that the available levels depend on the model.

The new variable is only a default, so it applies when nothing more specific is set. A subagent's own effort field beats it, and an effort Claude passes on a single call beats that field. The docs also say the effort field does not override the CLAUDE_CODE_EFFORT_LEVEL environment variable, so if you've already pinned that one, test your setup before you trust it.

A setup worth trying

For a typical day, keep the main session where you like it and push the helpers down:

1. Add "CLAUDE_CODE_SUBAGENT_EFFORT": "low" to the env block in ~/.claude/settings.json.
2. For a subagent that does real reasoning, like a code reviewer, give it its own effort: high line so it isn't caught by the low default.
3. If you also want cheaper models for the helpers, the docs cover CLAUDE_CODE_SUBAGENT_MODEL, which sets the default model for subagents the same way.
4. Run a normal task and compare it to yesterday's. If search-style subagents start missing files, move the default up to medium.

Here's what a lightweight helper can look like in .claude/agents/file-scout.md:

---
name: file-scout
description: Finds relevant files and summarizes what is in them
model: haiku
effort: low
---
List the files that match the request and give a two-line summary of each.

If you've been building your own agents and tools on top of Claude Code, our Claude Code mods examples post shows more of what that config layer can do.

Other changes in 2.1.316

The same release adds CLAUDE_CODE_DISABLE_ULTRATHINK, which turns off the ultrathink keyword. That's handy for a team that doesn't want one typed word bumping a turn's effort. The release also deprecates fast mode for Opus 4.8 as of October 30. Removal is set for November 30, and after that those requests return an error rather than falling back. Anthropic's suggested move is Opus 5.5, which we covered in Claude Opus 5.5 fast mode. And if you use the Claude Code extension in Cursor, make sure you're past the bad build covered in our 2.1.313 malware check.

What this means for teams using AI agents

Most automated workflows have the same shape as a Claude Code session: a few steps that need real judgment and a lot of lookups and busywork around them. Paying top rates for the busywork is an easy habit to fall into, and settings like this one make it easier to stop.

If you want help working out which parts of your own workflows need the heavy model and which can run cheap, New Face Design's free process audit is a good place to start.