Make Claude Code subagents cheaper: run quick ones at low effort

TL;DR Put one line in your CLAUDE.md saying which subagents run at low and which at high. Since v2.1.292, Claude turns it into an effort parameter on every subagent it starts. Without it, any subagent with no level of its own inherits your session's, and at max a five-line explanation costs 18 times more.

A subagent runs at your session's effort unless something gives it a level of its own. Raise the session to max for a hard problem and the subagent that only has to find a file reasons as deeply. Since v2.1.292, Claude can pass a different level to each subagent it starts: you only have to tell it which.

What the level costs on a quick task

Same general-purpose subagent, same task, only the level changed. Claude Code v2.1.311 on Sonnet 5.5, against a 360-line Python hook, one run per cell. Subagent output tokens and seconds, read from its transcript:

Up to xhigh, a mechanical task costs about the same at any level: effort is adaptive, and the model barely thinks when the task doesn't call for it. At max that stops. The same five-line explanation spent 18 times the output tokens and took nine times as long, and those are billed as output, the model's highest rate.

max is exactly the level you raise for a while: Claude Code applies it to the current session only. And every subagent without a level of its own inherits it. With the session launched with --effort max and a subagent nobody gave a level, the same explanation ran at max: 9,577 output tokens and 80 seconds.

Where a lower level does cost you

The same comparison on a bug review of the same hook:

At low, the top bug was a function returning a list shorter than its input; the code appends one item per line, so it isn't there. At high, the one that mattered showed up: an unclosed quote in the command makes the hook catch the exception and let the commit through unchecked. In a review, thinking is the product. There the level stays high.

Where each subagent gets its level

Claude Code resolves it in this order, and the first one present wins:

A file-finder agent with effort: low in its frontmatter ran at low without asking for anything. Asked for it "at high effort", Claude made this call and the subagent ran at high:

{"description": "Find file containing \"world\"", "subagent_type": "file-finder", "effort": "high", "prompt": "Find which file(s) in ... contain the word \"world\". Report the file path(s) and the matching lines."}

How to set it up

1. One line in your CLAUDE.md

Run search and lookup subagents at low effort. Run review subagents at high effort.

With that line in the project's CLAUDE.md and a prompt that never mentioned effort ("Use a general-purpose subagent to find which file contains the word world"), Claude passed "effort": "low" in the call. It also covers the agents that aren't yours, such as general-purpose, which have no frontmatter you can edit.

2. Pin it in your own agents' definitions

For an agent of your own that always does the same job, the level goes in its file:

---
name: file-finder
description: Finds files in the repo by name or content. Use for quick lookups.
tools: Glob, Grep, Read
effort: low
---
You find files. Answer with the paths only.

The full format is in creating custom agents. To also take it off your main model, model: haiku is the other half of the saving, covered in Haiku 5.5 subagents.

3. Check the level it ran at

In an interactive session, the /tasks panel adds the effort set for each subagent to its row. Outside one, every subagent leaves a .meta.json next to its transcript:

cat ~/.claude/projects/<project>/<session>/subagents/agent-*.meta.json

{"agentType":"general-purpose","isBuiltIn":true,"launchedWithDefaults":true,"description":"List files in folder","toolUseId":"toolu_01SyzkYKtHeftFPafzT47ZHn","spawnDepth":1,"requestShape":"background","requestNonInteractive":true,"effort":"low","finished":true}

No effort field means nobody set a level for that subagent, and it ran at your session's.

The cases you'll run into

• With CLAUDE_CODE_EFFORT_LEVEL set, the parameter is gone. With the variable at medium, Claude answered a request for a subagent at max with "the Agent tool has no effort parameter". The subagent ran at medium, over its own effort: low. If you use that variable, you set the level for all of them.
• Forks don't take it. The parameter is only for subagents that aren't a fork; a fork inherits the whole session.
• Resuming keeps the level. A subagent started at low stays at low when you send it another message.
• A level the model lacks drops to the highest one it has. xhigh runs as high on Opus 4.6. And a maxEffortLevel or organization cap still applies.
• Your session doesn't change. The level Claude passes to a subagent leaves yours alone: the session in these runs stayed at medium. To pin your session's level per model there's effort per model, and to find out which one you really have, effort is not the level you think.

Official docs: Sub-agents: choose an effort level · Model configuration: adjust effort level

Requirements

• Claude Code v2.1.292 or later for the effort parameter; the frontmatter effort field is older. The runs above used v2.1.311 on Sonnet 5.5 under -p, one run per cell: the figures change with the model and the task, and the jump at max is the one to watch.
• The /tasks panel, the level kept on resume and the fork case come from the docs.