[DOCS] Logic conflict between `MAX_THINKING_TOKENS` environment variable and `ultrathink` keyword

Resolved 💬 2 comments Opened Jan 14, 2026 by coygeek Closed Jan 16, 2026

Documentation Type

Unclear/confusing documentation

Documentation Location

https://platform.claude.com/docs/en/common-workflows#use-extended-thinking

Section/Topic

The "Use extended thinking (thinking mode)" section, specifically the "Per-request thinking with ultrathink" subsection.

Current Documentation

The documentation currently states:

"The ultrathink keyword only works when MAX_THINKING_TOKENS is not set. When MAX_THINKING_TOKENS is configured, it takes priority and controls the thinking budget for all requests."

What's Wrong or Missing?

This documentation describes a workflow flaw that creates significant friction for CLI users. In a terminal environment, users frequently set environment variables like MAX_THINKING_TOKENS in their shell profiles (.zshrc or .bashrc) as a global "safety rail" to control costs (e.g., setting it to 1024).

Under the current logic, if a user needs to perform a complex architectural task that requires deep reasoning, they cannot use the ultrathink keyword to "burst" to a higher token limit for that single request. The keyword is silently ignored in favor of the environment variable. This forces the user to manually unset their environment variable or restart their session to access the model's full reasoning capabilities, defeating the purpose of a per-request keyword.

Suggested Improvement

The documentation should reflect a change in logic where the explicit user intent of the ultrathink keyword overrides the passive environment variable for a single request.

Suggested revised text:

"The ultrathink keyword acts as a manual override for the MAX_THINKING_TOKENS environment variable. If you have a global limit set in your profile for cost control, using ultrathink in a prompt will allow Claude to use the full thinking budget (up to 31,999 tokens) for that specific request only."

If the current logic cannot be changed, the documentation should at least state that Claude Code will provide a warning in the UI when ultrathink is used while a conflicting environment variable is active.

Impact

High - Prevents users from using a feature

Additional Context

This issue is considered "Major" severity because it creates a circular block: the users most likely to use environment variables for safety are the same "power users" who need the ultrathink keyword for edge cases.