Claude Code token & thinking limits

Claude Code exposes a handful of environment variables that cap tokens in different places. They fall into two groups that behave very differently: model-side limits (thinking budget, output length — these change meaning per model) and harness-side limits (how much tool/file output the CLI pastes into the context — the same on every model). Knowing which is which is most of the battle.

Read this first: thinking is adaptive on current models

On Fable 5, Sonnet 5, and Opus 4.7+ (including Opus 4.8), thinking is adaptive — the model decides per step how much to think, steered by the effort level, not by a token budget. MAX_THINKING_TOKENS is ignored on these models. Reach for it only on the legacy models below.

The variables at a glance

Variable	Controls	Default	Group
`MAX_THINKING_TOKENS`	Fixed extended-thinking budget	none (adaptive models ignore it)	model-side
`CLAUDE_CODE_MAX_OUTPUT_TOKENS`	Max output tokens per response	varies by model	model-side
`MAX_MCP_OUTPUT_TOKENS`	Max tokens an MCP tool response can return	25,000 (warns at 10,000)	harness-side
`CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS`	Max tokens a single file read returns	harness default	harness-side
`CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`	Fall back to a fixed thinking budget	`0` (adaptive on)	model-side

Which models each applies to

	Adaptive models — Fable 5, Sonnet 5, Opus 4.7 / 4.8	Legacy — Opus 4.6, Sonnet 4.6
`MAX_THINKING_TOKENS`	Ignored. Control thinking with the effort level instead.	Works. Sets a fixed budget, `1` … `(max output tokens − 1)`; `0` disables thinking.
`CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1`	No effect (from v2.1.111 on).	Turns off adaptive reasoning so `MAX_THINKING_TOKENS` takes over.
`CLAUDE_CODE_MAX_OUTPUT_TOKENS`	Applies.	Applies.
`MAX_MCP_OUTPUT_TOKENS` / file-read cap	Applies (harness-side — model-independent).	Applies.

So on Opus 4.8 there is no way to pin a thinking-token budget — and no reason to want one. Use effort.

Controlling thinking: effort, not tokens

On current models, thinking is a dial, not a number:

claude --effort high        # low | medium | high | xhigh | max

Or change it mid-session with /effort. Adaptive reasoning means the model skips thinking on routine steps and spends it where it pays off, so a fixed budget would only make simple steps slower and expensive ones shorter. Nudge depth in the prompt or CLAUDE.md (“think carefully about X”) when you want more on a specific step.

Legacy fixed budget

Only if you have deliberately pinned to Opus 4.6 / Sonnet 4.6 does the old path apply: set CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 and MAX_THINKING_TOKENS=<n>. The budget must be less than the model’s max output tokens (ceiling is max output − 1). Thinking counts toward your quota and the output cap (billed at a 10% discount on the Anthropic API).

Set it for one session, or everywhere

One session only — export in the shell before launching. Gone when you close the terminal:

export MAX_MCP_OUTPUT_TOKENS=50000
claude

One project — commit an env block to .claude/settings.json in the repo:

{ "env": { "MAX_MCP_OUTPUT_TOKENS": "50000" } }

Every project, every session — the same env block in your user settings, ~/.claude/settings.json.

Precedence: a shell export and project settings both override user settings, so a per-session export is the safe way to try a value before making it permanent.

Recommended numbers — and why

These are pragmatic starting points, not doc-mandated defaults. The through-line: every token you let in is a token of context window spent, and a bigger output cap or bigger tool output means auto-compaction triggers sooner. Raise for completeness, keep modest otherwise.

Variable	Leave default when…	Raise when…	Sane value	Why not just max it
`CLAUDE_CODE_MAX_OUTPUT_TOKENS`	Normal work — the model default fits almost everything.	You need one very long response (large file gen, big diff).	Model default; only bump for a known big job.	Raising it shrinks usable context before compaction — you pay for headroom you rarely use.
`MAX_MCP_OUTPUT_TOKENS`	You rarely see “output exceeded” from tools.	A data-heavy MCP tool keeps getting truncated.	`50000`	Big tool dumps flood the context and crowd out the actual task.
`CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS`	Normal file reads.	You need a large file read whole rather than in chunks.	`50000`	A giant file read can eat most of a turn’s context in one shot.
`MAX_THINKING_TOKENS` (legacy only)	You’re on a current model — it does nothing.	Reproducing old Opus 4.6 / Sonnet 4.6 behavior.	`10000` light · `32000` heavy	Must stay under the output cap; higher just costs latency and quota.

Rule of thumb

On a current model, the only knobs worth touching are effort level (for thinking) and the two harness-side caps when a specific tool or file keeps getting truncated. Leave CLAUDE_CODE_MAX_OUTPUT_TOKENS at its default unless a single job genuinely needs a longer response, and ignore MAX_THINKING_TOKENS entirely.