Claude Code Effort Levels: Best Ultraplan Guide

Effort levels control how deeply Claude reasons before responding, shaping the quality, cost, and speed of every coding session. Claude Code exposes five tiers, from a lean low preset to a maximum-reasoning max mode, plus the adaptive auto reset. Choosing the right level for each task is the difference between a snappy fix and a runaway bill. This guide covers every command, environment variable, setting, priority rule, and known pitfall so you can dial in reasoning depth with confidence.

effort levels: What You’ll Learn

Effort levels are the single most powerful lever for balancing response quality against token cost in Claude Code. By the end of this guide you will understand the five canonical tiers, how to set them via commands, flags, environment variables, and settings files, and which level fits each kind of task. You will also learn how adaptive models differ from fixed-budget models and how enterprise admins enforce caps.

This tutorial assumes you have completed the initial setup and run at least a few sessions. If you are new to Claude Code, start with the getting-started guide, then return here to fine-tune your effort levels once you have a baseline workflow to optimize.

What Are Effort Levels in Claude Code?

An effort level is a named preset that tells Claude how much reasoning to invest before producing a response. Higher effort means more thinking tokens, deeper exploration of the codebase, and more detailed plans. Lower effort means faster, terser responses that consume fewer tokens. The setting influences every part of the output: the visible text answer, the tool calls Claude chooses to make, and the internal thinking trace.

Think of effort as a quality dial rather than a speed switch. At low, Claude produces a quick, direct answer with minimal exploration. At max, it methodically maps the problem space, considers alternatives, and plans multi-step solutions. Neither extreme is universally correct. The art is matching the level to the task at hand, which we cover in detail later.

Effort levels are not the same as model selection. You can run a powerful model at low effort for a trivial task, or a lighter model at high effort for focused reasoning. The two controls are complementary: model capacity sets the ceiling of capability, while effort controls how much of that capacity is spent on the current request.

The Five Effort Levels Explained

Claude Code defines five canonical effort levels, each calibrated for a different depth of reasoning. Understanding the intended use case for each helps you pick the right tier without trial and error. The table below summarizes the levels and their typical applications.

Low Effort

The low level instructs Claude to keep thinking brief and respond directly. It is ideal for tasks where the path is obvious: renaming a symbol, fixing a typo, adding a missing import, or answering a quick factual question about the codebase. At this level, Claude makes fewer tool calls and produces terser output, which keeps token consumption minimal.

Use low when you already know what needs to happen and just need Claude to execute it. It is also the recommended level for subagent tasks, where the subagent performs a narrow, well-defined operation and returns a compact summary to the main session. Pairing low effort with a cheaper model compounds the savings.

Medium Effort

The medium level provides moderate reasoning without excessive exploration. It suits routine refactoring across a handful of files, writing or updating documentation, and implementing features that follow established patterns in your codebase. Claude thinks enough to avoid careless mistakes but does not over-analyze straightforward work.

This is a sweet spot for everyday development. If you find high effort too verbose for mechanical tasks but low too shallow, medium fills the gap. Many developers set medium as their baseline and escalate only when a task proves trickier than expected.

High Effort (Default)

The high level is the out-of-the-box default for Claude Code. It delivers substantial reasoning, enough tool calls to verify assumptions, and detailed responses. For most general coding tasks, including implementing features, fixing non-trivial bugs, and answering architectural questions, high provides a reliable balance of quality and cost.

Because it is the default, you do not need to configure anything to use high. It persists across sessions and serves as the reference point from which other levels escalate or de-escalate. If you are ever unsure which level to use, high is a safe choice.

Extra High (xhigh) Effort

The xhigh level engages deep reasoning for genuinely complex work. Use it for intricate debugging where the root cause is hidden across multiple files, architectural decisions that ripple through the codebase, and problems that require considering several alternative approaches before settling on one. Claude invests significantly more thinking tokens at this level.

xhigh is also the recommended setting for long agentic runs where Claude operates with substantial autonomy. Because the model reasons more carefully about each step, it is less likely to take a wrong turn that compounds over a long session. The higher per-turn cost is often offset by fewer correction cycles.

Max Effort

The max level represents the fullest reasoning depth Claude Code offers through the standard API levels. It is designed for the hardest problems: subtle concurrency bugs, large-scale refactors with many interdependencies, and design questions where getting it wrong is expensive. At max, Claude explores exhaustively and plans meticulously.

An important constraint: max is session-only. It does not persist across sessions like the other levels. You set it with /effort max for the current session and it resets when you start a new one. This prevents accidentally leaving maximum reasoning on for routine work, which would inflate costs.

Ultraplan Mode (Claude Code Only)

Beyond the five API levels, Claude Code offers ultracode, which is not an API effort level at all. It pairs xhigh effort with standing permission for multi-agent workflows, allowing Claude to spawn and coordinate subagents without per-invocation confirmation. This is accessed only through the /effort interactive menu and is session-only.

Use ultracode when you want Claude to tackle a large, multi-faceted task autonomously, delegating subtasks to agents and synthesizing their results. Because it grants standing workflow permission, it is best reserved for scenarios where you trust the overall direction and want to minimize interruptions. For more on multi-agent patterns, see the advanced features guide.

Setting Effort with the /effort Command

The /effort command is the most direct way to change reasoning depth during a session. Type it followed by a level name, and Claude Code adjusts immediately. The command accepts low, medium, high, xhigh, max, and auto.

# Lower effort for a quick task
/effort low

Escalate for hard debugging
/effort xhigh

Maximum reasoning for the session
/effort max

Reset to automatic selection
/effort auto

Persistence Rules

Not all levels persist the same way. The low, medium, high, and xhigh levels persist across sessions, meaning your choice carries into the next session you start. The max level, by contrast, is session-only: it resets to your persistent level when you begin a new session. This design prevents runaway costs from an accidentally left-on maximum setting.

The auto argument is a reset, not a level. Running /effort auto tells Claude Code to select the effort dynamically based on task complexity, which is the behavior models use when no explicit level is set. This is useful when you have been manually escalating and want to return to adaptive defaults.

Interactive Menu

Running /effort with no arguments opens an interactive menu where you can select a level, including ultracode. This menu is the only way to activate ultracode, since it requires the accompanying workflow-permission toggle that the menu manages. The menu also shows your current level and whether it will persist.

Confirming the Active Level

If you are ever uncertain which effort level is active, run /effort without arguments and read the highlighted current value. This matters most when the environment variable is set, because in-session changes via /effort will appear to succeed but have no effect. The menu reflects the true effective level after the full priority chain resolves, so it is the authoritative source of truth. Checking before a costly operation prevents surprises on the next /usage report.

The CLAUDE_CODE_EFFORT_LEVEL Environment Variable

For automation, CI pipelines, and scenarios where you want effort locked regardless of what a user types in-session, the CLAUDE_CODE_EFFORT_LEVEL environment variable is the authoritative control. It accepts low, medium, high, xhigh, max, or auto.

# Lock effort to medium for a CI run
export CLAUDE_CODE_EFFORT_LEVEL=medium
claude --print "fix the failing lint checks"

Force maximum reasoning for a hard migration script
CLAUDE_CODE_EFFORT_LEVEL=max claude -p "refactor auth module"

Highest Precedence

The environment variable has the highest precedence of any effort control. It overrides the /effort command, the --effort CLI flag, and the effortLevel setting in settings.json. This makes it ideal for environments where you need a guaranteed, immutable effort level, such as shared CI runners or batch processing jobs.

Because it wins every conflict, setting CLAUDE_CODE_EFFORT_LEVEL effectively disables all in-session effort adjustments. If a user runs /effort max inside a session where the variable is set to medium, the session stays at medium. Use this deliberately when you want to prevent escalation, and avoid setting it in interactive developer environments where flexibility matters.

MAX_THINKING_TOKENS and Legacy Thinking Budgets

Before the effort-level system existed, thinking depth was controlled by MAX_THINKING_TOKENS, a legacy environment variable that directly caps the number of tokens allocated to reasoning. The default is 31,999 tokens, and the range runs from zero, which disables thinking entirely, up to that ceiling. On fixed-budget models, this variable works as documented.

# Disable thinking for the fastest possible responses
export MAX_THINKING_TOKENS=0

Cap thinking at 10,000 tokens to save cost
export MAX_THINKING_TOKENS=10000

The Forcing Behavior

A critical and often misunderstood behavior: setting MAX_THINKING_TOKENS to any nonzero value forces thinking on for every request, even for trivial prompts where reasoning adds cost without value. This is different from effort levels, which let the model decide when thinking is warranted. If you set the variable globally, you are opting every request into extended thinking.

This forcing behavior is why the effort-level system is now preferred. Effort levels allow adaptive models to skip thinking for simple prompts and engage it for complex ones, all within the selected depth tier. Hardcoding a token budget removes that adaptivity.

Ignored on Adaptive Models

On adaptive models, which include Opus 4.6 and later, any nonzero value of MAX_THINKING_TOKENS is ignored. The model uses its adaptive thinking mechanism, controlled by the effort level, instead. The only value that has an effect is 0, which disables thinking entirely even on adaptive models. This means setting MAX_THINKING_TOKENS=10000 on Opus 4.8 does nothing; you must use effort levels to control depth.

For fixed-budget models, such as Opus 4.5 and Haiku 4.5, the variable still works as documented. If you support a mix of models, be aware that the same environment variable behaves differently depending on which model a session targets. Prefer effort levels for consistency across model generations.

The –effort CLI Flag

When launching Claude Code from the terminal, the --effort flag sets the effort for that single session. It accepts the same level names as the /effort command except ultracode, which requires the interactive menu.

# Start a session at high effort
claude --effort high

Quick session at low effort for a small fix
claude --effort low

The flag is convenient for one-off sessions where you know the task complexity in advance. It sits below the environment variable in the priority chain, so if CLAUDE_CODE_EFFORT_LEVEL is set, the flag has no effect. Within the session, you can still run /effort to change levels, unless the environment variable is locking the value.

The flag does not persist. When you start your next session, effort returns to whatever is set in your configuration or the default. This makes --effort a good choice for situational overrides without committing to a persistent change.

The effortLevel Setting in settings.json

For a persistent default that applies to every session unless overridden, use the effortLevel field in your settings file. This is the right place to encode your personal or team baseline effort.

{
  "effortLevel": "medium"
}

Accepted Values

The effortLevel field accepts only low, medium, high, and xhigh. It does not accept max or ultracode. This restriction exists because max is intentionally session-only and ultracode requires interactive permission toggling. If you want max as a default, you must set it per-session via /effort or the environment variable.

If you accidentally write "effortLevel": "max" to settings.json, Claude Code ignores the invalid value and falls back to the model default. No error is raised, which can be confusing if you expect maximum reasoning and do not realize the setting was rejected. Always use one of the four accepted values.

Known Startup Bug

There is a known issue, tracked as GitHub issue #45453, where effortLevel in settings.json is sometimes not applied on startup. The session begins at the default instead of your configured level. The reliable workaround is to set CLAUDE_CODE_EFFORT_LEVEL in your environment, which has higher precedence and is consistently honored at startup.

If you notice your sessions starting at high despite a medium setting, this bug is the likely cause. Until the issue is resolved, treat the environment variable as the authoritative startup control and use the settings field as documentation of intent. For a complete reference of all configuration options, see the Claude Code Model Config Guide.

The Priority Chain Explained

Because effort can be set in multiple places, Claude Code resolves conflicts using a strict priority chain. Understanding this chain prevents confusion when a level seems stuck or ignored. The chain, from highest to lowest precedence, is as follows.

Skill frontmatter tops the chain. A skill can declare a preferred effort in its frontmatter, and when that skill is active, its declared level wins over everything else. This lets specialized skills request the depth they need without relying on the user to remember.

Below that, the environment variable is immovable within the process. Session-level values from /effort or --effort take precedence over the persistent setting, which in turn beats the model default. When troubleshooting an unexpected level, walk this chain from top to bottom to find the source.

Adaptive vs Fixed Thinking Models

How effort levels translate into actual reasoning depends on whether the model uses adaptive or fixed thinking. This distinction affects which controls work and how token budgets behave.

Adaptive Models

Adaptive models, including Opus 4.6, 4.7, 4.8, and Sonnet 5, dynamically allocate thinking tokens based on task complexity within the bounds of the selected effort level. The effort level sets the depth tier, and the model decides how many tokens to actually spend on each request. For a simple prompt at high effort, the model might use very few thinking tokens; for a complex prompt at the same level, it uses more.

On these models, MAX_THINKING_TOKENS is ignored for any nonzero value. The adaptive mechanism is the sole controller of depth, driven by the effort level. The only exception is MAX_THINKING_TOKENS=0, which disables thinking outright. This makes effort levels the primary and recommended control for modern models.

Fixed-Budget Models

Fixed-budget models, including Opus 4.5 and Haiku 4.5, use the traditional thinking budget. On these models, MAX_THINKING_TOKENS works as documented: it sets a hard cap on thinking tokens per request, and thinking is engaged up to that cap. Effort levels still apply, but the interaction with the token cap is more direct.

If your workflow spans both model generations, prefer effort levels as your primary control. They behave consistently across adaptive and fixed-budget models, whereas MAX_THINKING_TOKENS only affects fixed-budget models. This avoids the confusion of a variable that silently does nothing on newer models.

Effort’s Impact on Tokens and Cost

Effort is not free. Thinking tokens are billed as output tokens, which are the most expensive token category. Understanding the cost dynamics helps you make informed tradeoffs between depth and budget. Lower effort reduces thinking, which reduces tool calls and shortens responses, compounding the savings.

Token Composition

Effort affects all output tokens, not just the thinking trace. At lower effort, Claude produces terser text responses and makes fewer tool calls, both of which reduce output tokens. At higher effort, the model explores more files, runs more searches, and generates longer plans. The total token cost scales with all of these, not thinking alone.

This means the gap between low and max effort is larger than a naive thinking-token comparison suggests. A max session might use several times the total tokens of a low session for the same task, because the model reads more files and generates more elaborate output. Measure with /usage to see the real impact.

Cost Savings Example

Reducing MAX_THINKING_TOKENS from the default 31,999 to 10,000 can save approximately 70 percent on thinking costs for fixed-budget models. The same principle applies to effort levels: dropping from high to medium or low for tasks that do not need deep reasoning yields significant savings.

For a concrete example, consider a documentation task that takes 20 turns. At high effort, each turn might consume 5,000 thinking tokens plus verbose output. At medium, the same turns might use 1,500 thinking tokens and produce tighter responses. Over 20 turns, the difference is substantial. Match the level to the task.

Recommended Effort by Task Type

General guidance helps, but concrete recommendations for common task types make the decision faster. The table below maps typical development activities to the recommended effort level, based on the depth of reasoning each genuinely requires.

Use these as starting points, not absolutes. If a task at medium effort produces poor results, escalate rather than struggling. Conversely, if high effort is overkill for your typical work, drop to medium as your persistent default and escalate situationally.

Related Environment Variables

Beyond the primary controls, two environment variables modify how thinking behaves at a structural level. They are useful for edge cases and debugging, though they are not part of everyday configuration.

Disable Adaptive Thinking

Setting CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 forces adaptive models to fall back to a fixed thinking budget. This can be useful if you want predictable thinking token consumption on an adaptive model, or if you are debugging behavior that seems tied to the adaptive mechanism. When this is set, MAX_THINKING_TOKENS regains its effect on adaptive models.

# Force fixed-budget behavior on an adaptive model
export CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1
export MAX_THINKING_TOKENS=10000

Disable Thinking Entirely

Setting CLAUDE_CODE_DISABLE_THINKING=1 omits the thinking parameter from requests entirely. No thinking tokens are sent or billed. This produces the fastest, cheapest responses at the cost of reasoning quality. Use it for batch operations where speed and cost matter more than depth, such as generating many boilerplate files.

Note that disabling thinking is different from setting MAX_THINKING_TOKENS=0. The former removes the parameter from the API call; the latter sends a budget of zero. In practice, both suppress thinking, but the disable flag is cleaner for automation scripts. For official details, see the Claude Code settings documentation.

Thinking Settings in settings.json

Two boolean fields in settings.json control thinking behavior at a display and enablement level. They complement the effort controls by managing whether thinking happens at all and how it appears.

{
  "alwaysThinkingEnabled": true,
  "showThinkingSummaries": true
}

The alwaysThinkingEnabled field, when set to true, enables extended thinking for every request. This is the settings-file equivalent of the forcing behavior that MAX_THINKING_TOKENS produces. Use it if you want thinking guaranteed regardless of effort level, though note the cost implications.

The showThinkingSummaries field, when true, expands the thinking display so you can see Claude’s reasoning in the interface. This is valuable for understanding how Claude arrived at an answer, especially during debugging or code review. When false, thinking still happens but is hidden from view.

Keyboard Shortcuts for Thinking

Two keyboard shortcuts let you toggle thinking without leaving your flow. Learning these keeps your hands on the keyboard during fast iterations.

The Option+T or Alt+T shortcut toggles whether thinking is enabled for the current session. This is useful for quickly disabling thinking for a batch of simple tasks, then re-enabling it for a complex one. The toggle persists for the session.

The Ctrl+O shortcut toggles the verbose display, which controls whether thinking summaries are shown inline. This affects visibility, not whether thinking occurs. Use it to reduce visual noise when you trust the output and want a cleaner view.

Organization Controls and Enterprise Caps

In enterprise deployments, administrators can enforce maximum effort levels per model and per role. This prevents individual users from accidentally or intentionally running expensive configurations that strain the organization’s budget or rate limits. Caps are set per-model, so an admin can allow xhigh on Sonnet but cap Opus at high.

When a cap is in place, any attempt to set effort above the cap, whether via /effort, the flag, or the environment variable, is clamped to the cap. The user is informed that the requested level exceeds the organizational limit. This makes caps transparent rather than silently overriding.

For teams, caps provide predictable cost forecasting. By limiting the maximum reasoning depth per model, admins can estimate the upper bound of per-session token consumption and plan rate limit distribution accordingly. Pair caps with the subagent delegation patterns to keep aggregate costs predictable even as the team grows.

The Shared Budget Warning

A subtle but important detail: thinking tokens share the total output token budget with tool calls. The output budget is not unlimited. If you set MAX_THINKING_TOKENS very high, or run at max effort on a task that also requires many tool calls, the thinking allocation can squeeze the space available for tool results, causing them to truncate.

Truncated tool results are problematic because Claude may make decisions based on incomplete data without realizing the output was cut off. Symptoms include Claude re-reading the same file repeatedly or acting on partial information. If you see this pattern, check whether an excessively high thinking budget is crowding out tool output.

The fix is to balance the two. For tasks that require both deep reasoning and extensive tool use, prefer effort levels over hardcoded token budgets, since adaptive models allocate thinking dynamically and leave room for tool output. If you must use MAX_THINKING_TOKENS on a tool-heavy task, set it conservatively.

A Worked Example

Let us walk through a realistic scenario that puts effort management into practice. Imagine you are debugging an intermittent test failure in a payment processing module. The failure happens roughly one in twenty runs, involves a race condition between two async operations, and has resisted two prior attempts at a fix. This is exactly the kind of problem where effort level makes or breaks the session.

You start by setting effort to max for this session, since the problem is subtle and prior shallow attempts failed. You run /effort max and confirm the level is active. Claude invests heavily in reasoning, mapping the async flow, identifying the two operations that race, and tracing the timing dependency. The thinking summary, visible because you have showThinkingSummaries enabled, shows Claude considering three hypotheses before settling on the likely cause.

Claude reads four relevant files, consuming about 7,200 tokens of file content, and identifies that a shared counter is incremented without a lock in one code path. It proposes a fix using a mutex and explains why the prior fixes missed this path. The fix is applied, and Claude suggests running the flaky test in a loop to verify. You run the test fifty times; all pass.

With the bug fixed, you no longer need maximum reasoning. You run /effort medium to drop back down for the remaining work: updating a comment, adding a regression test, and writing a brief changelog entry. These tasks are mechanical and do not benefit from deep thinking. At medium, Claude handles them quickly and tersely.

You check /usage at the end. The max portion of the session, which involved the actual debugging, consumed the bulk of the tokens. The medium portion, covering the documentation and test writing, was inexpensive. Had you left effort at max for the entire session, the documentation tasks alone would have cost several times more without producing better results. The effort-level adjustment saved an estimated 60 percent on the second half of the session.

This example illustrates the core habit: escalate effort when a problem resists, then de-escalate once the hard work is done. Treat effort as a situational dial, not a set-and-forget setting. Over a week of sessions, the savings from matching effort to task complexity compound significantly.

effort levels: Common Mistakes to Avoid

Even experienced developers make predictable mistakes with effort levels. Most stem from treating effort as a one-time configuration rather than a situational control. Recognizing these patterns helps you avoid wasted tokens and suboptimal results.

• Leaving max effort on persistently: Because max is session-only, some developers re-enable it at the start of every session out of habit. This inflates costs on trivial tasks. Reserve max for genuinely hard problems and drop to high or medium for routine work.
• Setting MAX_THINKING_TOKENS on adaptive models: On Opus 4.6 and later, nonzero values are ignored. If you believe you are capping thinking but see no effect, this is why. Use effort levels instead, which work consistently across model generations.
• Forgetting that max does not persist: If you set /effort max and expect it to carry into tomorrow’s session, it will not. The level resets to your persistent default. Set effortLevel in settings.json or the environment variable if you want a durable baseline.
• Ignoring the shared output budget: Setting a very high thinking budget on tool-heavy tasks can truncate tool results, leading to decisions based on incomplete data. Balance thinking and tool allocations, especially when using MAX_THINKING_TOKENS on fixed-budget models.

effort levels: Best Practices

• Match the effort level to task complexity: use low for simple fixes, medium for routine work, high for general coding, and xhigh or max for debugging and architecture. Adjust dynamically within a session as the task shifts.
• Prefer effort levels over MAX_THINKING_TOKENS on modern adaptive models, since the legacy variable is ignored for nonzero values and removes the model’s ability to allocate thinking dynamically based on prompt complexity.
• Use CLAUDE_CODE_EFFORT_LEVEL in CI and automation to lock effort immutably, preventing unexpected escalation in batch jobs where predictable cost matters more than flexibility.
• Escalate effort when a problem resists a first attempt, then de-escalate once the hard reasoning is complete. This situational adjustment can cut session costs by half or more without sacrificing quality on the difficult portions.
• Check /usage after changing effort to confirm the token impact matches your expectations, and verify the level is active with /effort if results seem off, since the priority chain can override in-session changes silently.

effort levels: Frequently Asked Questions

What are the five effort levels in Claude Code?

The five canonical levels are low, medium, high (the default), xhigh, and max. Additionally, ultracode is a Claude Code-only mode pairing xhigh effort with standing multi-agent workflow permission, available session-only via the /effort interactive menu.

Which control has the highest precedence?

Skill frontmatter has the highest precedence, followed by the CLAUDE_CODE_EFFORT_LEVEL environment variable, then the session value from /effort or --effort, then the effortLevel setting, and finally the model default. The environment variable overrides all in-session and settings-based controls.

Does MAX_THINKING_TOKENS work on all models?

No. On adaptive models like Opus 4.6 and later and Sonnet 5, nonzero values are ignored because the model allocates thinking dynamically via effort levels. Only MAX_THINKING_TOKENS=0 has an effect, disabling thinking entirely. On fixed-budget models like Opus 4.5 and Haiku 4.5, the variable works as documented.

Why does not max effort persist across sessions?

The max level is intentionally session-only to prevent runaway costs from an accidentally left-on maximum setting. The low, medium, high, and xhigh levels persist, but max resets to your persistent default when you start a new session. Re-enable it with /effort max when needed.

How much can lowering effort save on cost?

Reducing MAX_THINKING_TOKENS from 31,999 to 10,000 can save roughly 70 percent on thinking costs for fixed-budget models. Effort level reductions yield similar proportional savings, since lower effort means fewer thinking tokens, terser responses, and fewer tool calls, all of which reduce billed output tokens.

Effort levels are the quality dial for Claude Code reasoning, spanning low through max plus the adaptive auto reset. Set them via the /effort command, the --effort flag, the CLAUDE_CODE_EFFORT_LEVEL environment variable, or the effortLevel setting, and remember the priority chain when troubleshooting. Match the level to the task, escalate when problems resist, and de-escalate once the hard work is done to keep both quality and cost in balance.