Deep reasoning in Claude Code: effort levels and extended thinking

Claude Code controls reasoning depth with effort levels (low, medium, high, xhigh, max), set through /effort, the --effort flag, an environment variable, or settings. On current models thinking is adaptive: the model decides per step how much to think within the chosen level. Higher effort pays off on ambiguous, multi-system problems, and tests, not the reasoning itself, prove the result.

This page is for developers who already run Claude Code daily, and for tech leads who set effort defaults and caps for a team. The situation it solves: an order endpoint times out for 3% of requests at peak, only since last week’s payment integration. You describe it and get “add retry logic”. That is a guess, not an analysis. You need Claude to reason through the connection pool, the new outbound call, and the gateway timeout. Then you need a test that proves which explanation is true. If you have not set up settings files yet, start with configuration.

What you’ll walk away with from effort tuning

• A decision table that maps the kind of task to an effort level, and the order to escalate in before you switch model.
• The exact commands and settings that set effort for one turn, one session, one model, a subagent, or a whole organisation.
• Three copy-paste prompts that turn deep reasoning into falsifiable hypotheses, a testable architecture decision, and a measured comparison of two effort levels.
• A verification routine that checks the output with tests and review gates, so you never have to audit the reasoning line by line.
• Fixes for the seven ways effort settings fail or backfire, each with its recovery step.

Everything below was checked against the installed CLI, Claude Code 2.1.283 (claude --help), and the official model configuration documentation on 2026-09-26.

How does effort control Claude’s reasoning?

Effort is the primary control for how much Claude thinks. On adaptive-reasoning models, thinking is optional on each step. At a low level Claude answers routine steps quickly. At a high level it spends more tokens exploring before it acts. Anthropic calibrates the scale per model, so high on one model is not the same amount of thinking as high on another.

Each model starts at its own default:

Model in Claude Code	Effort levels	Default effort	Can thinking be turned off?
Claude Opus 5.5 (the default model)	low to max	medium	No
Claude Fable 5.1, Claude Fable 5	low to max	high	No
Claude Sonnet 5, Claude Opus 5, Claude Opus 4.8	low to max	high	Yes
Claude Opus 4.7	low to max	xhigh	Yes
Claude Opus 4.6, Claude Sonnet 4.6	low, medium, high, max (no xhigh)	high	Yes
Claude Haiku 4.5	No effort parameter	—	Yes

Two consequences matter more than the table:

• Opus 5.5 starts one level lower than Opus 5 did. Anthropic’s Claude Code docs say that in its testing Opus 5.5 at medium matches or exceeds Opus 5 at high on coding and knowledge-work evaluations. Anthropic also reports that Opus 5.5 at its default effort beats Opus 5 at max on Terminal-Bench 4.0 for about a fifth of the cost (anthropic.com, 2026-09-22). Both are vendor claims. Do not carry your old Opus 5 level over; start at medium and raise it only when a task shows you need to.
• Your release channel decides the default model. Opus 5.5 is the default from v2.1.280, which on 2026-09-26 is the latest channel only. On the stable channel (2.1.274) you still run Opus 5 or Sonnet 5 at high. Run /status for the model, and /effort status or read the session header for the effort level. Model prices and context sizes live on the models hub.

If you set a level the model does not support, Claude Code falls back to the highest level it supports at or below the one you set. For example, xhigh runs as high on Opus 4.6 and Sonnet 4.6.

Which effort level should you use?

Pick by how much the task depends on reasoning across moving parts, not by how important it feels.

Level	Use it for	Example
low	Short, scoped, latency-sensitive steps that need little judgement	Rename a symbol, fix a lint error, write a commit message
medium	Everyday feature work and cost-sensitive runs. The Opus 5.5 default	Add an endpoint that follows an existing pattern
high	Bugs without a clear reproduction, multi-file changes with hidden coupling	An intermittent timeout that appeared after a deploy
xhigh	Long agentic exploration and design work across several systems	Choose between a queue and a synchronous call for payments
max	Problems an expert would need hours on. Anthropic warns it can overthink, so test it before adopting it	A concurrency bug that survived two xhigh attempts
ultracode	Large tasks you want split into a dynamic workflow. A Claude Code setting, not a model level: it sends xhigh and adds workflow orchestration	Migrate 40 services to a new logging API

Escalate in this order, and stop at the first step that works:

1. Improve the prompt. Add the symptom, the constraint, and the evidence. A vague prompt at max loses to a precise prompt at medium.
2. Raise effort one level for the session, or add ultrathink for one turn.
3. Switch model deliberately. Anthropic’s own guidance is to reach for Claude Fable 5.1 (/model fable) when your evals on Opus 5.5 at higher effort still fall short. Fable 5.1 is never a default, and it may bill to usage credits depending on your plan.

Caution

ultrathink is the only keyword that deepens reasoning for one turn. It adds an in-context instruction for that turn and does not change the effort level sent to the API. The separate ultracode keyword turns on xhigh plus workflow orchestration (see the ultracode row above). Phrases such as “think hard” or “think more” are ordinary prompt text (checked in Claude Code 2.1.283). There is no /think or /ultrathink command either (commands reference, checked 2026-09-26).

Set the effort level for a turn, session, or model

Claude Code resolves effort in a fixed order. The first source that applies wins:

1. An explicit choice: the CLAUDE_CODE_EFFORT_LEVEL environment variable, the --effort flag, or /effort in the session.
2. Your settings: the level saved for the model under modelSettings, or an effortLevel key.
3. The model’s own default from the table above.

Use these commands, from the narrowest scope to the widest:

1. Check what is active. In a session, run:

   /effort status

   The session header also shows the level next to the model name, for example “with low effort”.

2. Deepen a single turn. Put ultrathink anywhere in the prompt. The session level stays unchanged.

3. Change the level for this session or save it for this model. Run /effort with no argument to open the slider. Press Enter to save the level as your default for the active model, or s to apply it to this session only (v2.1.257 or later). Typing a level, such as /effort high, saves it. /effort auto clears the saved level. max and ultracode chosen with /effort apply to this session only. To keep max, set CLAUDE_CODE_EFFORT_LEVEL=max; to keep ultracode, set "ultracode": true in settings.

4. Start a session at a level. In the terminal:

   claude --effort xhigh

   claude --effort ultracode starts at xhigh with ultracode on.

5. Pin a level for a whole shell or CI job. The environment variable overrides every other source, including /effort:

   export CLAUDE_CODE_EFFORT_LEVEL=high

   It accepts low to max, auto, or unset (both hand the choice back to the other sources), but not ultracode.

6. Pin a level on a subagent or skill. Add effort to the frontmatter of a file in .claude/agents/ or a skill’s SKILL.md. A read-only reviewer that must reason deeply can run at high while the main session stays at medium:

   ---
   name: concurrency-reviewer
   description: Reviews diffs that touch locks, pools, queues, or async code for race conditions.
   tools: Read, Grep, Glob
   effort: high
   ---

   Frontmatter overrides the session level but not the environment variable. See custom subagents for the full format.

Set effort defaults and caps for a team

Tech leads have two settings keys, both documented in the settings reference:

• effortLevel sets a default for models with no saved level. It accepts low, medium, high, or xhigh, never max. In project, local, or managed settings it applies to every model. In a user’s own ~/.claude/settings.json it no longer applies to Opus 5.5 or later models, because /effort now saves levels per model.
• maxEffortLevel caps effort. Any higher request runs at the cap, whatever set it. Deploy it in managed settings to enforce it for an organisation. A cap below xhigh also makes ultracode unavailable.

{
  "maxEffortLevel": "xhigh"
}

This cap keeps max, which Anthropic’s docs describe as prone to overthinking, out of routine use while leaving ultracode available. Pair it with the spend controls in cost control.

See what Claude reasoned, and what it costs

Claude Code collapses thinking by default. Press Ctrl+O to expand the transcript and see the reasoning as gray italic text. Interactive sessions on the Anthropic API receive redacted thinking blocks unless you set "showThinkingSummaries": true in your settings. Redaction changes only what you see: every thinking token counts toward your cost or plan usage, shown or not. Check session spend with /usage.

Treat the visible reasoning as a debugging aid, not as evidence. Read it when the answer surprises you and you need to know which assumption led there. Do not read it to decide whether the answer is correct; the tests in the verification section below decide that.

Old thinking controls that no longer apply to the default model

Earlier guides, including earlier versions of this page, tell you to toggle thinking. Those controls still exist, but on Opus 5.5 and the Fable models thinking cannot be turned off, and they have no effect there:

• Option+T (macOS) or Alt+T (Windows and Linux) toggles thinking for the session.
• /config sets the global default, saved as alwaysThinkingEnabled in ~/.claude/settings.json.
• MAX_THINKING_TOKENS=0 turns thinking off on the Anthropic API, except on Opus 5.5 and Fable.
• Fable, Sonnet 5 and Opus 4.7 and later always use adaptive reasoning, so positive MAX_THINKING_TOKENS values do nothing there. Opus 4.6 and Sonnet 4.6 can return to a fixed budget with CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1; Haiku 4.5 has no effort parameter and keeps a manual thinking budget.

On the default model, effort is the only lever. To reduce thinking, lower effort.

Prompts that make deep reasoning pay off

Effort buys more thinking. The prompt decides whether that thinking ends in something you can check. Each prompt below asks for falsifiable output: hypotheses with tests, a decision with acceptance criteria, or a measured comparison.

Copy-paste prompt: intermittent bug to falsifiable hypotheses

ultrathink. /api/orders returns 504 for about 3% of requests between 14:00 and 16:00 UTC,
starting after the payment integration was deployed last Tuesday. Database query time stays
under 50 ms and memory is flat. Read @src/pages/api/orders.ts and @src/lib/payments.ts.

Do not change application code yet. List at most four hypotheses, ranked by likelihood. For each one give:
1. the mechanism, citing file and line;
2. a test or measurement that would fail if the hypothesis is true and pass if it is false;
3. the evidence that would rule it out.
Then write the test for the top hypothesis only, run it, and report whether it fails.

Copy-paste prompt: architecture decision with acceptance criteria

We must decide how /api/orders confirms payment: (A) keep the synchronous call to the payment
provider with a 2-second timeout and a circuit breaker, or (B) accept the order as "pending"
and confirm payment in a queue consumer. Constraints: p99 latency for
/api/orders must stay under 800 ms, clients already poll order status, and the v1 API
response shape cannot change.

Explore the codebase first, then write docs/adr/0007-payment-confirmation.md with: context,
both options, failure modes of each (provider outage, duplicate webhook, retry storm), the
recommendation, and five acceptance criteria phrased as tests we can automate. Mark every
assumption you could not confirm from the code as UNVERIFIED.

Calibrate effort on your own task

The table above is a starting point. Running the same task at two levels on your own code tells you more than any general rule. In the terminal, from the repository root, give both runs a task that has a test to pass. Commit or stash your changes first: git worktree add ... HEAD checks out the last commit, so uncommitted work would not be under test. A new worktree also has no node_modules, so install dependencies in each one before the runs:

git worktree add ../effort-medium HEAD
git worktree add ../effort-high HEAD
(cd ../effort-medium && npm ci)
(cd ../effort-high && npm ci)
TASK="Make tests/orders/timeout.test.ts pass without editing that test file."
(cd ../effort-medium && claude -p "$TASK" --effort medium --permission-mode acceptEdits --allowedTools "Bash(npm test *)")
(cd ../effort-high && claude -p "$TASK" --effort high --permission-mode acceptEdits --allowedTools "Bash(npm test *)")

--permission-mode acceptEdits lets each headless run edit files, and --allowedTools lets it run only your test command. Put the prompt before --allowedTools: the flag takes several values and would swallow the prompt as a second tool rule, so the run exits with “Input must be provided” (checked in 2.1.283). Then compare the two results in a normal session:

Copy-paste prompt: compare two effort runs

Compare the worktrees ../effort-medium and ../effort-high. In each one, run npm test and
npx tsc --noEmit, and collect git diff --stat against HEAD. Check that
tests/orders/timeout.test.ts is unchanged in both. Give me a table with: tests passed, tests
failed, type errors, files changed, lines changed, and whether the test file was modified.
Then tell me which run I should keep and why, in three sentences. Do not merge or delete anything.

Repeat this on three to five representative tasks before you change a team default, and weigh any gain against the extra usage that /usage reports.

Plan at high effort, then build at the default

Plan mode and effort combine well because a plan is where extra reasoning is cheapest. A wrong plan costs one reply; a wrong implementation costs a revert.

1. Enter plan mode with /plan, or cycle to it with Shift+Tab.
2. Raise effort for planning: run /effort, move the slider to xhigh, and press s so the change stays session-only.
3. Describe the change and ask for a plan that lists the files to touch, the tests to add, and the acceptance criteria.
4. Review the plan against your acceptance criteria, and push back on anything that is not testable.
5. Before you approve it, return to your usual level: run /effort, move the slider back and press s (or /effort auto if you never saved a level for this model). Then let Claude implement.

Changing effort mid-conversation can invalidate the prompt cache, and Claude Code may warn you before it applies the change. Change it at a turn boundary rather than back and forth. The opusplan model alias automates a similar split between models: Opus in plan mode, Sonnet for execution. For deeper planning workflows, see feature planning and architecture decisions.

How do you verify deep-reasoning output without reading it all?

A longer chain of thought is more convincing, and not more likely to be true. Judge the output by what it lets you check.

Output	Gate that proves it	Who signs off
A bug diagnosis	A reproduction test that fails on the current code and passes after the fix, committed with the fix	The developer
A fix	The full test suite, type check, and lint in CI; /code-review on the diff	The developer, then the PR reviewer
An architecture decision	An ADR whose acceptance criteria are written as automated tests; every UNVERIFIED assumption resolved or accepted by name	The tech lead
An effort default for the team	The calibration comparison, repeated on three to five representative tasks	The tech lead

Two rules keep this honest. First, never let the agent edit the test that proves its own fix; see protect the oracle. Second, when the diagnosis names a mechanism you cannot test, treat it as a hypothesis, not a finding. For the full debugging loop, see debugging with Claude Code.

When effort settings don’t do what you expect

Higher effort gives the same wrong answer. The problem is missing context, not missing reasoning. Add the log excerpt, the failing request, or the file that owns the behaviour, and connect the data source through MCP if it lives outside the repo. Then retry at the same level.

/effort changes nothing. Something with higher precedence is set. Run echo $CLAUDE_CODE_EFFORT_LEVEL in the terminal; the environment variable beats /effort. Then check for a maxEffortLevel cap in managed settings, and remember that xhigh falls back to high on Opus 4.6 and Sonnet 4.6. /effort status shows the level actually applied.

Your saved effortLevel is ignored after the upgrade to Opus 5.5. A top-level effortLevel in user settings no longer applies to Opus 5.5. Run /effort high once in a session on Opus 5.5 and press Enter; Claude Code saves it under modelSettings for that model.

The thinking toggle does nothing. You are on Opus 5.5 or a Fable model, where thinking is always on. Lower effort to reduce thinking.

ultracode will not turn on. It needs a model that supports xhigh, no effort cap below xhigh, and workflows turned on. CLAUDE_CODE_EFFORT_LEVEL set to anything other than xhigh also keeps its orchestration inactive.

Usage runs out halfway through the week. You left max or xhigh on for routine work. Return to the model default with /effort auto, reserve higher levels for named tasks, and ask your tech lead for a maxEffortLevel cap. /usage shows where the tokens went.

Claude circles on an ambiguous problem at max. Anthropic’s docs warn that max can overthink. Narrow the question (“only the connection-pool lifecycle, not the whole request path”), drop to xhigh, and ask for the single most likely hypothesis with its test.

Where to go next with deep reasoning

For other tools: Codex has its own reasoning-effort levels (see Codex configuration), and Cursor chooses reasoning through its model picker (see Cursor model selection).

MCP setup Give Claude your logs, database, and issue tracker so deep reasoning has evidence to work with

Error recovery Rewind, checkpoints, and recovery when a session goes wrong

Debugging with Claude Code The full hypothesis-to-regression-test loop

Models hub Current models, prices, and context windows in one place