Claude Extended Thinking: Complete Guide

Extended thinking is Claude's most underused power feature. It gives the model a private scratchpad to reason through problems before responding — and the difference in output quality is dramatic.

Most developers either don't know it exists or don't understand when to reach for it. This guide covers exactly how extended thinking works, when it helps, when it hurts, and how to implement it in production.

What Extended Thinking Actually Is

When you enable extended thinking, Claude gets a budget of internal reasoning tokens — a private chain-of-thought that happens before the visible response. The model can use these tokens to break down problems, consider alternatives, catch its own mistakes, and plan its answer.

You never see the thinking tokens in the final output (unless you explicitly request them via the API). But you see the results: more accurate answers, fewer hallucinations, better-structured responses on complex tasks.

Think of it like the difference between answering a math problem in your head versus working it out on paper first. The paper doesn't show up in your final answer, but the answer is better because you used it.

How It Differs from Chain-of-Thought Prompting

Chain-of-thought prompting ("think step by step") asks Claude to show its reasoning in the visible output. Extended thinking is fundamentally different:

• Chain-of-thought — reasoning is visible, consumes output tokens, and the model performs for the audience. It may simplify or skip steps to seem concise.
• Extended thinking — reasoning is private, uses a separate token budget, and the model reasons for itself. No performance pressure. More honest internal deliberation.

The private nature matters more than you'd expect. When Claude knows the reasoning won't be shown, it's more likely to explore dead ends, reconsider assumptions, and catch errors — the same way a human thinks more freely in a private notebook than in a presentation.

When to Use Extended Thinking

Extended thinking is not a "turn it on everywhere" feature. It adds latency and cost. Use it when the quality gain justifies both.

High-Value Use Cases

• Complex analysis — multi-step reasoning, comparing options, weighing trade-offs. Financial modeling, legal document review, architectural decisions.
• Code generation for complex systems — designing APIs, refactoring large codebases, debugging subtle issues. The thinking budget lets Claude plan the approach before writing code.
• Math and logic — any problem where the answer requires multiple reasoning steps. Extended thinking dramatically reduces arithmetic errors and logical fallacies.
• Agentic workflows — when Claude is making decisions about which tools to call, what order to execute steps, or how to handle edge cases. The planning phase produces better action sequences.
• Safety-critical outputs — medical information, legal advice, financial recommendations. The extra reasoning catches hedging that should be assertions and assertions that should be hedges.

When to Skip It

• Simple retrieval — "What's the capital of France?" doesn't need a reasoning scratchpad.
• Structured extraction — pulling fields from a document into JSON. The task is mechanical, not analytical.
• High-throughput pipelines — if you're processing thousands of items per minute, the latency cost of thinking tokens may not be worth the quality gain. Test empirically.
• Real-time chat — users waiting for a response notice the extra latency. For conversational UIs, the delay often outweighs the quality improvement.

How to Enable Extended Thinking in the API

Extended thinking is controlled by the thinking parameter in the Messages API:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    messages=[{
        "role": "user",
        "content": "Design a rate limiting system for a multi-tenant API that handles 10K requests per second with fair queuing."
    }]
)

The budget_tokens parameter sets the maximum number of tokens Claude can use for internal reasoning. This is separate from max_tokens, which controls the visible output length.

Reading the Thinking Output

The response includes thinking blocks alongside text blocks:

for block in response.content:
    if block.type == "thinking":
        print(f"Thinking ({len(block.thinking)} chars):")
        print(block.thinking[:500])  # preview
    elif block.type == "text":
        print(f"Response:")
        print(block.text)

In production, you typically ignore thinking blocks and only use the text output. But during development, reading the thinking gives you insight into how Claude approaches your problem — invaluable for prompt debugging.

TypeScript Example

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const response = await client.messages.create({
  model: "claude-opus-4-6",
  max_tokens: 16000,
  thinking: {
    type: "enabled",
    budget_tokens: 10000,
  },
  messages: [{
    role: "user",
    content: "Review this contract clause for potential liability issues: ...",
  }],
});

for (const block of response.content) {
  if (block.type === "thinking") {
    console.log("Model reasoning:", block.thinking.slice(0, 200));
  } else if (block.type === "text") {
    console.log("Final answer:", block.text);
  }
}

Budget Tokens: How Much Thinking Is Enough?

The budget_tokens parameter is a ceiling, not a target. Claude uses as many thinking tokens as it needs, up to the limit. Setting a budget of 10,000 doesn't mean Claude will always use 10,000 — for simple problems, it might use 500.

Practical Guidelines

Start with 10,000 for most use cases. Monitor actual usage via the response's usage field, then adjust. Overshoot is cheap — the model stops thinking when it's ready, so unused budget tokens cost nothing.

The Usage Object

# Check actual thinking token usage
print(f"Input tokens: {response.usage.input_tokens}")
print(f"Output tokens: {response.usage.output_tokens}")
# Thinking tokens are included in the output token count
# but billed at a different rate

Critical Constraints

Extended thinking has a few hard rules that will bite you if you miss them:

1. Temperature Must Be Unset

When thinking is enabled, you cannot set a temperature value. The API will reject the request. This isn't a style preference — the reasoning process requires the model's full probability distribution to explore solution paths effectively.

If you need both reasoning and deterministic output, split the work into two calls: a thinking-enabled call to plan, then a temperature-0 call to produce the final structured output. We cover this pattern in our temperature settings guide.

2. System Prompts Work Differently

System prompts still work with extended thinking, but be aware: the thinking process may reference or reinterpret your system prompt in ways that affect the final output. Keep system prompts clear and unambiguous when using thinking mode — vague instructions get amplified by the reasoning process. Our custom instructions guide covers how to write effective system prompts.

3. Streaming Behavior

When streaming with extended thinking enabled, you'll receive thinking blocks before text blocks. The thinking stream can be long — plan your UI accordingly. Many production systems show a "reasoning..." indicator during the thinking phase, then display the text response.

with client.messages.stream(
    model="claude-opus-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[{"role": "user", "content": prompt}]
) as stream:
    for event in stream:
        if event.type == "content_block_start":
            if event.content_block.type == "thinking":
                print("[reasoning...]")
            elif event.content_block.type == "text":
                print("[answering...]")
        elif event.type == "content_block_delta":
            if hasattr(event.delta, "thinking"):
                pass  # optionally log thinking
            elif hasattr(event.delta, "text"):
                print(event.delta.text, end="")

4. Model Compatibility

Extended thinking is available on Claude Opus 4.6, Sonnet 4.6, and Haiku 4.5. Older models (Opus 4.0, Sonnet 4.0) do not support it. Always use current model IDs when building with thinking.

What Changes on Claude Fable 5

Everything above applies to Opus, Sonnet, and Haiku models, where the Messages API is unchanged. Claude Fable 5 — released June 9, 2026 — works differently. Adaptive thinking is the only mode: it applies whenever the thinking parameter is unset, and thinking: {"type": "disabled"} is not supported. Instead of tuning budget_tokens, you control reasoning depth with the effort parameter.

Fable 5 also never returns the raw chain of thought. Thinking blocks contain either a readable summary ("summarized") or an empty field ("omitted", the default), set via thinking.display. If your debugging workflow depends on reading raw thinking — covered below — that workflow stays on Opus 4.6 and Sonnet 4.6.

For who gets Fable 5, what it costs, and the June 22 subscription deadline, see our Fable 5 vs Mythos 5 access guide.

Production Patterns

Pattern 1: Think-Then-Execute

The most common production pattern. Use thinking to plan, then a separate call to execute with tight constraints:

# Step 1: Think about the approach
plan = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=8000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[{"role": "user", "content": f"Plan the implementation for: {task}"}]
)

# Extract the plan from the text response
plan_text = next(b.text for b in plan.content if b.type == "text")

# Step 2: Execute with deterministic settings
result = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4000,
    temperature=0,
    messages=[{
        "role": "user",
        "content": f"Execute this plan exactly. Output JSON only.\n\nPlan:\n{plan_text}\n\nInput:\n{data}"
    }]
)

This gives you the quality benefits of extended thinking with the reproducibility of deterministic output. The planning call uses Opus for depth; the execution call can use Sonnet for speed and cost.

Pattern 2: Thinking as Quality Gate

Use thinking to review and validate output before it reaches users:

# Generate initial output
draft = generate_response(user_query)

# Use thinking to review it
review = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=8000,
    thinking={"type": "enabled", "budget_tokens": 8000},
    messages=[{
        "role": "user",
        "content": f"""Review this AI-generated response for accuracy, 
        completeness, and potential issues. If it passes, 
        return it unchanged. If not, return a corrected version.
        
        Original query: {user_query}
        Draft response: {draft}"""
    }]
)

final = next(b.text for b in review.content if b.type == "text")

Pattern 3: Agentic Decision-Making

In agent architectures, extended thinking improves tool selection and sequencing:

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=4000,
    thinking={"type": "enabled", "budget_tokens": 5000},
    tools=tool_definitions,
    messages=[{
        "role": "user",
        "content": "Find all customers who churned last month, analyze common factors, and draft a retention email template."
    }]
)

Without thinking, Claude might call tools in a suboptimal order or miss steps. With thinking, it plans the full sequence before making the first tool call — resulting in fewer round trips and better outcomes.

Cost and Latency

Extended thinking tokens are billed as output tokens. The cost depends on the model:

A 10,000-token thinking budget on Opus costs up to $0.75 per call if fully used. On Sonnet, the same budget costs up to $0.15. In practice, most calls use a fraction of the budget.

Latency impact: expect 2-10 seconds of additional time for the thinking phase, depending on budget size and problem complexity. For Sonnet, thinking adds 1-5 seconds typically.

Cost Optimization Tips

1. Right-size the budget. Monitor usage.output_tokens and reduce the budget to 1.5x your P95 actual usage.
2. Use thinking selectively. Route simple queries to a non-thinking path and complex ones to thinking-enabled endpoints.
3. Choose the right model. Sonnet with thinking often matches or exceeds Opus without thinking — at a fraction of the cost.
4. Cache thinking results. If the same analysis applies to multiple downstream tasks, run thinking once and reuse the plan.

Debugging with Thinking

One of the most underappreciated benefits of extended thinking: it makes debugging dramatically easier. When Claude produces a wrong answer, the thinking trace tells you why.

# Development mode: log thinking for debugging
for block in response.content:
    if block.type == "thinking":
        with open("thinking_log.txt", "a") as f:
            f.write(f"--- {datetime.now()} ---\n")
            f.write(block.thinking)
            f.write("\n\n")

Common patterns you'll find in thinking traces:

• Misinterpreted instructions — the model understood your prompt differently than you intended. Fix the prompt, not the output.
• Missing context — the model noted it was guessing because key information wasn't provided. Add it to the prompt or system message.
• Correct reasoning, wrong conclusion — the model reasoned well but made an error in the final step. Often a formatting or extraction issue, not a logic issue.
• Overthinking — the model explored too many alternatives and lost track of the best one. Constrain the prompt to narrow the solution space.

Extended Thinking vs. Claude Code

If you've used Claude Code (Anthropic's agentic coding tool), you've seen extended thinking in action. Claude Code uses thinking mode by default for complex coding tasks — it's why the tool can handle multi-file refactors and architectural decisions that would trip up a non-thinking model.

The key insight from Claude Code's architecture: thinking works best when paired with tool use. The model reasons about what tools to call, in what order, with what parameters — then executes the plan. This pattern generalizes to any agentic system you build.

Common Mistakes

1. Setting Budget Too Low

A budget of 1,000 tokens is barely enough for the model to restate the problem. For any non-trivial task, start at 5,000 minimum. Underthinking produces worse results than not thinking at all — the model starts reasoning but gets cut off mid-thought.

2. Using Thinking for Simple Tasks

Extended thinking on a classification task doesn't make the classification better — it just makes it slower and more expensive. Match the tool to the task complexity.

3. Ignoring the Thinking Trace During Development

The thinking trace is the best debugging tool you have. If you're not reading it during development, you're flying blind. Log it, read it, learn from it.

4. Setting Temperature with Thinking

The API will reject this, but developers still try it. If you need randomness in your output, generate multiple thinking-enabled responses and pick the best one — don't try to control sampling during the reasoning phase.

The Bottom Line

Extended thinking is the difference between Claude answering off the top of its head and Claude actually working through the problem. For complex tasks — code architecture, analysis, agentic planning — the quality improvement is substantial and measurable.

Start with a 10,000-token budget on Sonnet for most use cases. Monitor actual usage, read thinking traces during development, and route simple tasks to a non-thinking path. The goal is surgical application: thinking where it matters, speed where it doesn't.

Ready to go deeper? Our CCA Exam Prep course covers extended thinking as part of Domain 2 (Model Configuration). For combining thinking with function calling, see our tool use guide. And if you're building production systems with thinking, we consult.