[DOCS] Document the difference between `ultrathink` and Thinking Mode On/Off

[PaulRBerg]

Documentation Type

Missing documentation (feature not documented)

Section/Topic

Thinking Mode

What's Wrong or Missing?

In Claude Code v1, there used to be three different thinking levels:

• think
• think hard (more thinking)
• ultrathink (even more thinking)

Now, in Claude Code V2, you deprecated these thinking levels, and introduced a new "Thinking On/Off" mode that is toggleable by pressing TAB.

I noticed you removed the color highlighting for think and think hard, but they kept ultrathink.

Suggested Improvement

The question is - how does Thinking On/Off relate to ultrathink? Do they complement each other?

Impact

Medium - Makes feature difficult to understand

[greetclammy]

Agreed 👍

Reddit post about this: https://www.reddit.com/r/ClaudeCode/comments/1nyly8m/what_is_the_difference_between_thinking_onoff_and/

[github-actions[bot]]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

[greetclammy]

Bump

[uschtwill]

I guess it's documented here now?

[Hansehart]

@uschtwill Unfortunately there is no single occurrence of /ultrathink. Maybe it's deprecated or just visuals and a gimmick. Nonetheless the prompts seem to affect the depth of thinking.

[sarahdeaton]

Hi @PaulRBerg and @greetclammy 👋

Thanks so much for raising this issue. We've updated the documentation to address these questions; here's a summary:

How Thinking Mode and ultrathink work together

Thinking Mode (On/Off)

• Turn thinking mode on or off via /config → sets your global default
  • Note: this is a recent change; thinking mode used to be toggled on/off with Tab, but now you set it in your /config
• Thinking mode is binary: you allocate either 0 tokens (thinking mode off) or 31,999 tokens (thinking mode on) for thinking

ultrathink keyword

• A per-request override you can use in any prompt (e.g., ultrathink: design a caching layer)
• Bypasses your global configuration and enables thinking just for that request even if thinking mode is off in your /config
• Also semantically signals to Claude to reason more thoroughly, which may result in deeper thinking
  • The total allocated token budget for thinking remains the same, but the keyword might signal to Claude to think more than it would if you didn't use the keyword

Clarifications:

• Only ultrathink is the special keyword that enables thinking on a per-request basis. Phrases like "think", "think hard", "think more" don't have any impact on the allocated thinking token budget.
• If you need fine-grained control over the token budget (vs. just allocating all 31,999 tokens to the thinking budget), you can set the MAX_THINKING_TOKENS environment variable. This setting takes priority over ultrathink, so if you set a lower MAX_THINKING_TOKENS threshold, ultrathink doesn't override it.

Documentation links

• Use extended thinking (thinking mode)
• Per-request thinking with ultrathink
• How extended thinking token budgets work

Thanks for flagging this and let us know if you have any other questions!

[ltawfik]

docs have been updated