What Do Claude Code Effort Levels Actually Mean?
The Problem
I noticed something strange in March 2026. My Claude Code sessions felt different. The responses seemed shallower. Complex debugging tasks that used to work flawlessly now required more back-and-forth. I hadn’t changed anything in my configuration.
Then I discovered the issue: Anthropic silently changed the default effort level from high to medium for Pro and Max subscriptions. But what does “effort level” even mean?
I tried searching for answers and found conflicting information:
- Some said it’s a token budget
- Others claimed it controls thinking time
- A few insisted it’s just a marketing label
The documentation was sparse. Reddit discussions were chaotic. I needed to figure out what these five levels actually do: low, medium, high, xhigh, and max.
What Effort Levels Actually Control
After digging through official docs, Reddit threads, and SDK documentation, I found the answer. Effort levels are behavioral signals that adjust how eagerly Claude spends tokens across thinking, response generation, and tool calls.
┌─────────────────────────────────────────────────────────────┐│ ││ Effort Level affects ALL token types: ││ ││ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ││ │ Thinking │ │ Text │ │ Tool Calls │ ││ │ Tokens │ │ Output │ │ Appetite │ ││ └──────────────┘ └──────────────┘ └──────────────┘ ││ ││ Higher effort = more aggressive use of all three ││ │└─────────────────────────────────────────────────────────────┐This is NOT a strict token budget. It’s a behavioral adjustment. Think of it like telling Claude “how hard should you try” rather than “how much can you spend.”
Key Distinction: Effort vs Thinking Budget
Many people confuse these two parameters. They are independent:
EFFORT LEVEL: - Affects: thinking + text + tool calls - Nature: Behavioral signal (how eagerly to spend) - Values: low, medium, high, xhigh, max
THINKING BUDGET: - Affects: Only thinking tokens - Nature: Hard cap (maximum thinking tokens) - Values: numeric token limit (e.g., 8192, 16384)
You can combine them: high effort with 8K thinking budgetThe Five Levels Explained
Here’s what each level actually does:
┌────────┬─────────────────────────────────────────────────────┐│ Level │ Behavior │├────────┼─────────────────────────────────────────────────────┤│ low │ Minimal reasoning, quick responses ││ │ Frequently asks for clarification ││ │ Stops and checks direction often │├────────┼─────────────────────────────────────────────────────┤│ medium │ Moderate reasoning depth ││ │ Balanced persistence through tasks ││ │ Good default for production systems │├────────┼─────────────────────────────────────────────────────┤│ high │ Deep reasoning, thorough exploration ││ │ Sonnet default model setting ││ │ Pushes through obstacles │├────────┼─────────────────────────────────────────────────────┤│ xhigh │ Very deep reasoning, aggressive problem-solving ││ │ Opus default model setting ││ │ High tool call appetite │├────────┼─────────────────────────────────────────────────────┤│ max │ Maximum reasoning depth ││ │ Relentless persistence through complex workflows ││ │ Highest token consumption │└────────┴─────────────────────────────────────────────────────┘When to Use Each Level
| Level | Best Use Cases | Avoid When |
|---|---|---|
| low | Simple queries, file edits, summaries, high-volume batch processing | Complex debugging, architectural decisions |
| medium | Routine production tasks, cost-sensitive workflows, simple refactoring | Deep research, multi-file analysis |
| high | Feature development, debugging, code review, complex analysis | Simple one-line fixes |
| xhigh | Multi-file refactoring, architectural decisions, security audits | Quick prototype iterations |
| max | Deep research, complex agentic workflows, critical production bugs | Everyday tasks (wasteful) |
Why the March 2026 Change Matters
The default shift from high to medium explains why many users noticed quality degradation without any configuration changes. This wasn’t documented prominently, causing confusion across the community.
Model-Specific Defaults (unchanged): Haiku 4.5 → medium (default) Sonnet 4.6 → high (default) Opus 4.7 → xhigh (default)
Subscription Defaults (changed March 2026): Pro/Max plans → medium (was high) This explains the "feels worse" complaintsIf you’re on a Pro or Max plan and noticed Claude Code being less thorough, explicitly set higher effort:
# CLI flagclaude --effort high
# Interactive command/effort high
# Environment variableexport CLAUDE_CODE_EFFORT_LEVEL=highA Critical Insight: Context Quality Over Effort
A Reddit user (ng37779a) shared something that changed my approach entirely:
“Effort level is partly a context-quality proxy. A model on Low with great context often outperforms the same model on Max with poor context.”
I tested this and found it true. Here’s what I discovered:
Scenario: Debug a failing authentication module
Test 1: Max effort + vague prompt Prompt: "Fix the auth bug" Result: 15 turns, still broken, spent $3.20
Test 2: Low effort + detailed context Prompt: "Auth fails on /login endpoint. Stack trace shows JWT decode error. Here's the failing test file. Here's the JWT config." Result: 3 turns, fixed, spent $0.40
Better context at low effort > max effort with poor contextEffort amplifies good context. It does not compensate for bad context.
Even Low Effort Still “Thinks”
A common misconception: low effort disables thinking. It doesn’t.
The Reddit OP clarified:
"Even at low effort, Claude still thinks on difficult problems."
Low effort doesn't turn off reasoning.It changes the *behavioral approach*: - Less aggressive exploration - More pauses for user input - Quicker decision-making - Lower tool call appetite
But if the problem is genuinely hard,Claude will still reason through it.This matters because some users avoid low thinking it will produce “dumb” responses. That’s not how it works. The model adapts based on problem complexity.
How Effort Affects Agentic Behavior
In multi-step workflows, effort changes how Claude behaves:
┌──────────────────────────────────────────────────────────────┐│ ││ LOW: "I found issue A. Should I investigate B?" ││ [Pauses for user input frequently] ││ ││ MEDIUM: "I found issue A. Let me check B too." ││ [Some autonomy, some checkpoints] ││ ││ HIGH: "Found A. Checking B, C, D. Also found E." ││ [Thorough exploration, fewer pauses] ││ ││ XHIGH: "A → B → C → D → E → F → G. Found root cause." ││ [Aggressive problem-solving] ││ ││ MAX: "A through K analyzed. Here's full report." ││ [Relentless, exhaustive approach] ││ │└──────────────────────────────────────────────────────────────┘The Reddit user goship-tech explained this well:
“Effort level affects how persistently the model pushes through multi-step agentic work. On Low, it tends to pause and ask for clarification more often.”
Practical Settings Guide
Here’s how to set effort levels in different contexts:
| Method | Command | When to Use |
|---|---|---|
| CLI flag | claude --effort high | Starting a session with known complexity |
| Interactive | /effort max | Mid-session when task becomes complex |
| Environment | export CLAUDE_CODE_EFFORT_LEVEL=xhigh | Permanent default override |
| SDK | output_config: {effort: "high"} | Programmatic control in scripts |
For SDK usage:
response = client.messages.create( model="claude-opus-4-5-20251101", max_tokens=1024, betas=["effort-2025-11-24"], output_config={ "effort": "high" }, messages=[...])Common Mistakes
I’ve made all of these:
Mistake 1: Max effort for everything
Task: Change button color from blue to redUsed: max effortCost: $0.80, 5 thinking blocks, 3 tool callsShould have used: low effortCorrect cost: ~$0.05, 1 turnMistake 2: Staying on default medium after March 2026
Task: Debug complex race condition in async codeUsed: medium (default)Result: Took 12 turns, incomplete fixShould have used: high or xhighCorrect result: 5 turns, thorough fixMistake 3: Ignoring context quality
WRONG: Vague prompt + max effort = expensive, unfocused
RIGHT: Detailed context + appropriate effort = efficient, targeted
Invest time in prompt quality before cranking effortMistake 4: Assuming effort disables thinking
WRONG belief: Low effort = Claude stops thinking
REALITY: Low effort = Claude thinks differently (quicker decisions, more checkpoints, less exploration)
Even at low, hard problems trigger reasoningMistake 5: Not combining with thinking budget
For precise control, combine both:
high effort + 8K thinking budget = Thorough reasoning but capped
xhigh effort + 16K thinking budget = Very deep reasoning with explicit limit
This gives you quality control + cost predictabilityQuick Decision Guide
When choosing an effort level, I use this mental model:
┌─────────────────────────────────────────────────────────────┐│ ││ Is this task routine/simple? ││ └────────────────────YES──→ LOW ││ ││ Does it involve 1-2 files with clear scope? ││ └────────────────────YES──→ MEDIUM ││ ││ Does it need debugging, analysis, multi-file review? ││ └────────────────────YES──→ HIGH ││ ││ Is it architectural, security-related, or complex refactor?││ └────────────────────YES──→ XHIGH ││ ││ Is it deep research or critical production issue? ││ └────────────────────YES──→ MAX ││ ││ Bonus question: Is my context/prompt detailed? ││ └────YES──→ Can lower effort level safely ││ └────NO───→ Fix context first, then consider effort ││ │└─────────────────────────────────────────────────────────────┘Summary
Claude Code effort levels (low/medium/high/xhigh/max) are behavioral signals, not token budgets. They control:
- Reasoning depth - How thoroughly Claude explores problems
- Agentic persistence - How aggressively it pushes through multi-step workflows
- Tool call appetite - How many tools it’s willing to invoke
The March 2026 default change from high to medium explains why your Claude Code might feel less thorough than before. The fix is simple: explicitly set higher effort when needed.
The most important insight: context quality often matters more than effort level. A well-prepared prompt at low effort can outperform a vague prompt at max effort. Invest in your context before cranking up the effort dial.
Final Words + More Resources
My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me
Here are also the most important links from this article along with some further resources that will help you in this scope:
- 👨💻 Claude API Docs - Effort Parameter
- 👨💻 Claude Code Effort Levels Explained - MindStudio
- 👨💻 Claude Code Getting Worse? Two Settings - Pasquale Pillitteri
- 👨💻 Reddit r/ClaudeAI: Claude Code effort levels explained
Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!
Comments