Claude Code Ultrathink: One Turn of Deeper Reasoning

Direct answer

Claude Code ultrathink is a recognized prompt keyword that requests deeper reasoning for one turn. The application adds an in-context instruction, but the effort level sent to the API stays unchanged. This guide helps you use it selectively and verify the outcome.

Summary: Claude Code ultrathink

Add `ultrathink` anywhere in one prompt when a difficult decision deserves a deeper pass. Choose `/effort` when you want a session-level setting. A better prompt, relevant evidence, and explicit verification still matter more than the keyword alone.

Good candidates include architecture trade-offs, elusive root causes, data migrations, security-sensitive plans, and risky multi-system changes. Routine edits, formatting, direct lookups, and well-specified mechanical work usually need less effort.

Use a six-stage loop. Define the problem, collect evidence, request ultrathink, compare options, verify the chosen path, and record the decision.

How ultrathink works now

Current Claude Code recognizes the exact word `ultrathink` anywhere in a prompt. It asks the model for deeper reasoning through an instruction in context. The request applies to that turn and does not change the session effort setting.

The official documentation also states that `think`, `think hard`, and `think more` pass through as ordinary prompt text. Do not rely on old ladders that assign fixed thinking budgets to those phrases.

Claude Code's current model configuration guide defines ultrathink, effort levels, model selection, settings precedence, adaptive reasoning, and extended thinking.

Put the keyword in a complete prompt

The keyword is not a substitute for the task. Give Claude the decision, evidence, constraints, risks, and output format. Place `ultrathink` anywhere in that prompt.

Example: Ultrathink about this database migration. Inspect the current schema, queries, deployment order, rollback path, and production constraints. Compare at least three viable approaches. Recommend one, state the trade-offs, list assumptions, and define the checks that could disprove it. Do not edit files yet.

Outcome: the decision or artifact you need from the turn.
Evidence: files, logs, documentation, metrics, constraints, and known failures to inspect.
Scope: systems included, systems excluded, and the boundary of the current decision.
Risks: data loss, authorization, downtime, compatibility, cost, latency, or recovery concerns.
Alternatives: require more than one credible option before recommending a path.
Verification: define tests, evidence, and review that would validate or reject the recommendation.

Ultrathink is not the effort setting

Effort is a separate control for how much work the model applies across a response. It affects reasoning, visible text, tool calls, and function arguments. Available levels and defaults depend on the selected model and provider.

Use `ultrathink` for a deeper pass on the next turn without changing the session effort setting.
Run `/effort` to view or change the effort level for the session.
Adjust effort in `/model` when selecting a supported model.
The `--effort` flag launches a session with a specific level.
Use settings or the environment variable when you need a repeatable default and understand precedence.
Use skill or subagent frontmatter when that bounded workflow needs an effort override.

Higher effort can increase time and token use. The deepest levels can show diminishing returns or overthinking. Test a representative task set before changing the default for a team.

Anthropic's platform effort guide explains how effort affects thinking, text, tool calls, token use, latency, and task-level evaluation.

Model choice and effort solve different problems

The model defines the underlying capability, context, provider availability, and behavior. Effort changes how much work that model applies. Ultrathink adds a one-turn instruction for deeper reasoning. These controls can interact, but they are not interchangeable.

Change the model when the task needs different capability, context, speed, availability, or provider support.
Change session effort when a stream of tasks deserves a different intelligence and usage trade-off.
Use ultrathink when one decision inside the session deserves a deeper pass.
Improve the evidence when the model lacks repository facts, logs, source documentation, or acceptance criteria.
Reduce the scope when one prompt contains several decisions that should be reviewed separately.

Adaptive reasoning still needs direction

Supported models can decide when and how much to reason within the available control. A higher setting creates room for more work, but it cannot identify missing goals or repair contradictory requirements.

State the decision instead of asking for a broad analysis of the entire repository.
Provide the authoritative files and current behavior before asking for alternatives.
Ask for assumptions and unknowns so confidence is visible.
Separate investigation, recommendation, implementation, and verification when the change is risky.
Require a stopping condition for long searches or repeated experiments.

When ultrathink is useful

Use it when the cost of a shallow decision is higher than the extra reasoning cost. The task should contain a real trade-off, uncertain evidence, or a failure mode that deserves explicit analysis.

Architecture: compare boundaries, dependencies, migration paths, operations, and long-term ownership.
Root cause: reconcile logs, code paths, timing, environment differences, and competing hypotheses.
Migration: reason about ordering, compatibility, backfill, validation, rollback, and partial failure.
Security: examine trust boundaries, permissions, attacker paths, sensitive data, and containment.
Performance: compare evidence across profiling, queries, rendering, network behavior, and resource limits.
Review: challenge a high-risk plan before any irreversible or expensive action begins.

When to skip ultrathink

Extra reasoning is not the first remedy for missing context or an oversized task. Fix the input and scope before increasing effort.

Formatting, renaming, copy corrections, and other mechanical changes with clear acceptance criteria.
Direct questions answered by one current source or a small, known code path.
Implementation where the approved plan and exact affected files are already known.
Repeated attempts that lack new evidence, a changed hypothesis, or a tighter experiment.
Prompts that combine research, architecture, implementation, migration, deployment, and review without boundaries.
Tasks where faster feedback from a test, profiler, log, or user is more valuable than another reasoning pass.

Use a verification-first workflow

Define the decision, success criteria, constraints, excluded scope, and person who owns the outcome.
Collect primary evidence from the repository, runtime, logs, metrics, documentation, and current system behavior.
Ask Claude to investigate and use ultrathink for the bounded decision, without editing files yet.
Compare alternatives by correctness, risk, reversibility, maintenance, performance, security, and delivery cost.
Choose one approach and record assumptions, rejected options, migration order, rollback, and open questions.
Implement the smallest reversible slice with normal code review and permission controls.
Run tests and observed checks that can disprove the reasoning, then revise the decision if evidence changes.

The Claude Code commands guide covers session controls, built-in commands, project commands, and safe team conventions.

Evaluate accepted outcomes

Do not rate a setting by how thoughtful the answer sounds. Compare accepted results on representative tasks. Keep the model, repository state, prompt, permissions, and checks stable enough to make the comparison useful.

Correctness: accepted tests, observed behavior, and factual support.
Decision quality: credible alternatives, explicit trade-offs, assumptions, and reversibility.
Review effort: time needed to find and fix unsupported claims or weak code.
Efficiency: elapsed time, token use, tool calls, repeated work, and usage-limit impact.
Safety: permission boundaries, destructive-action handling, secret protection, and rollback quality.
Completion: whether the agreed outcome holds after implementation and verification.

Control usage and latency

A one-turn keyword can still lead to more reasoning and a longer response. Watch the usage tools available to your plan, keep tasks bounded, and avoid repeating the same request without new evidence.

Use normal effort for routine work and reserve deeper requests for high-value decisions.
Ask for an investigation plan before expensive tools or broad repository reads.
Stop once the decision has enough evidence for implementation and review.
Start a fresh bounded task when old context is noisy or unrelated.
Track accepted-result cost instead of comparing raw response length alone.
Let administrators set model and effort policy where organization controls require it.

Troubleshoot ultrathink

No special behavior appears: update Claude Code and confirm the current model configuration documentation.
The keyword is not highlighted: terminal theme can affect its rainbow display, but display styling is not proof of output quality.
The answer is long but weak: provide evidence, reduce scope, require alternatives, and define verification.
The session stays expensive: check `/effort`, model selection, environment variables, settings, and organization policy.
A team sees inconsistent results: record the model, effort, Claude Code version, prompt, repository state, and accepted checks.
Old guides conflict: prefer the current official model configuration page over fixed token budgets and retired phrase ladders.

Frequently asked questions

It is a recognized keyword that requests deeper reasoning for one turn. The application adds an in-context instruction and leaves the effort level sent to the API unchanged.

Include the exact word `ultrathink` anywhere in a complete prompt. It applies to that turn and does not change the session effort setting.

No. Ultrathink is a one-turn prompt instruction. Effort levels are separate model controls. Current options, defaults, and session-only levels can vary by model and Claude Code version.

Current official documentation does not define it as a fixed token budget. It describes an in-context request for deeper reasoning while the API effort level remains unchanged.

No. Reserve it for bounded difficult decisions. Routine work benefits more from a precise brief, relevant evidence, smaller scope, and normal verification.

Connect Better Design