From b95a4170b7b1a78a0397ab9ce28911e19a7d242c Mon Sep 17 00:00:00 2001 From: Huanyi Xie <74809554+xiehuanyi@users.noreply.github.com> Date: Tue, 6 Oct 2026 10:33:25 +0300 Subject: [PATCH 1/3] docs(performance): explain adaptive reasoning effort controls --- .cursor/rules/common-performance.md | 17 +++++++++++------ rules/common/performance.md | 17 +++++++++++------ 2 files changed, 22 insertions(+), 12 deletions(-) diff --git a/.cursor/rules/common-performance.md b/.cursor/rules/common-performance.md index ef4114025..750bbb3a3 100644 --- a/.cursor/rules/common-performance.md +++ b/.cursor/rules/common-performance.md @@ -36,16 +36,21 @@ Lower context sensitivity tasks: ## Extended Thinking + Plan Mode -Extended thinking is enabled by default, reserving up to 31,999 tokens for internal reasoning. +In Claude Code, adaptive reasoning lets the model choose how much to think for each task. +For Fable models, Sonnet 5 and later, and Opus 4.7 and later, use effort to control reasoning +rather than a fixed token budget. Available levels depend on the model. -Control extended thinking via: -- **Toggle**: Option+T (macOS) / Alt+T (Windows/Linux) -- **Config**: Set `alwaysThinkingEnabled` in `~/.claude/settings.json` -- **Budget cap**: `export MAX_THINKING_TOKENS=10000` (bash) or `$env:MAX_THINKING_TOKENS = "10000"` (PowerShell) +Control thinking via: +- **Effort**: Use `/effort` in a session, `--effort ` at launch, or `CLAUDE_CODE_EFFORT_LEVEL`. Save a per-model level in `modelSettings` in `~/.claude/settings.json`; the older user-level `effortLevel` key does not apply to Opus 5.5 or newer models. +- **Toggle**: Option+T (macOS) / Alt+T (Windows/Linux), or `alwaysThinkingEnabled` in settings. These cannot disable thinking on Opus 5.5, Sonnet 5.5, or Fable models. +- **Fixed budget**: A positive `MAX_THINKING_TOKENS` does not cap adaptive reasoning. On Opus 4.6 or Sonnet 4.6, set `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` to use a fixed budget with `MAX_THINKING_TOKENS`. - **Verbose mode**: Ctrl+O to see thinking output +See [Claude Code model configuration](https://code.claude.com/docs/en/model-config#adjust-effort-level) +and [environment variables](https://code.claude.com/docs/en/env-vars) for supported controls. + For complex tasks requiring deep reasoning: -1. Ensure extended thinking is enabled (on by default) +1. Choose a higher supported effort level, such as `/effort high` 2. Enable **Plan Mode** for structured approach 3. Use multiple critique rounds for thorough analysis 4. Use split role sub-agents for diverse perspectives diff --git a/rules/common/performance.md b/rules/common/performance.md index 0a2f22977..e8daa4174 100644 --- a/rules/common/performance.md +++ b/rules/common/performance.md @@ -32,16 +32,21 @@ Lower context sensitivity tasks: ## Extended Thinking + Plan Mode -Extended thinking is enabled by default, reserving up to 31,999 tokens for internal reasoning. +In Claude Code, adaptive reasoning lets the model choose how much to think for each task. +For Fable models, Sonnet 5 and later, and Opus 4.7 and later, use effort to control reasoning +rather than a fixed token budget. Available levels depend on the model. -Control extended thinking via: -- **Toggle**: Option+T (macOS) / Alt+T (Windows/Linux) -- **Config**: Set `alwaysThinkingEnabled` in `~/.claude/settings.json` -- **Budget cap**: `export MAX_THINKING_TOKENS=10000` (bash) or `$env:MAX_THINKING_TOKENS = "10000"` (PowerShell) +Control thinking via: +- **Effort**: Use `/effort` in a session, `--effort ` at launch, or `CLAUDE_CODE_EFFORT_LEVEL`. Save a per-model level in `modelSettings` in `~/.claude/settings.json`; the older user-level `effortLevel` key does not apply to Opus 5.5 or newer models. +- **Toggle**: Option+T (macOS) / Alt+T (Windows/Linux), or `alwaysThinkingEnabled` in settings. These cannot disable thinking on Opus 5.5, Sonnet 5.5, or Fable models. +- **Fixed budget**: A positive `MAX_THINKING_TOKENS` does not cap adaptive reasoning. On Opus 4.6 or Sonnet 4.6, set `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` to use a fixed budget with `MAX_THINKING_TOKENS`. - **Verbose mode**: Ctrl+O to see thinking output +See [Claude Code model configuration](https://code.claude.com/docs/en/model-config#adjust-effort-level) +and [environment variables](https://code.claude.com/docs/en/env-vars) for supported controls. + For complex tasks requiring deep reasoning: -1. Ensure extended thinking is enabled (on by default) +1. Choose a higher supported effort level, such as `/effort high` 2. Enable **Plan Mode** for structured approach 3. Use multiple critique rounds for thorough analysis 4. Use split role sub-agents for diverse perspectives From 57ea31338514771aaec3fa8b1bc8c261903a613e Mon Sep 17 00:00:00 2001 From: Huanyi Xie <74809554+xiehuanyi@users.noreply.github.com> Date: Tue, 6 Oct 2026 10:54:14 +0300 Subject: [PATCH 2/3] docs(performance): align thinking cost recommendations --- README.md | 6 ++++-- docs/token-optimization.md | 14 +++++++++----- 2 files changed, 13 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 95673de4b..b1b306ac9 100644 --- a/README.md +++ b/README.md @@ -1718,7 +1718,7 @@ Add to `~/.claude/settings.json`: { "model": "sonnet", "env": { - "MAX_THINKING_TOKENS": "10000", + "CLAUDE_CODE_EFFORT_LEVEL": "medium", "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50", "CLAUDE_CODE_SUBAGENT_MODEL": "haiku" } @@ -1728,10 +1728,12 @@ Add to `~/.claude/settings.json`: | Setting | Default | Recommended | Impact | |---------|---------|-------------|--------| | `model` | opus | **sonnet** | ~60% cost reduction; handles 80%+ of coding tasks | -| `MAX_THINKING_TOKENS` | 31,999 | **10,000** | ~70% reduction in hidden thinking cost per request | +| `CLAUDE_CODE_EFFORT_LEVEL` | Model-dependent | **medium** | Controls adaptive reasoning depth; lower effort trades reasoning depth for latency and cost | | `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 95 | **50** | Compacts earlier, better quality in long sessions | | `ECC_CONTEXT_MONITOR_COST_WARNINGS` | on | **off for subscription users** | Suppresses agent-facing API-rate estimate warnings while keeping context/scope/loop warnings | +For fixed-budget models, `MAX_THINKING_TOKENS` controls the thinking budget. On Opus 4.6 or Sonnet 4.6, also set `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` to use that mode. A positive token value does not cap adaptive reasoning; see the [performance rule](rules/common/performance.md#extended-thinking--plan-mode). + Switch to Opus only when you need deep architectural reasoning: ``` /model opus diff --git a/docs/token-optimization.md b/docs/token-optimization.md index 03a10e1f8..f3bf9259a 100644 --- a/docs/token-optimization.md +++ b/docs/token-optimization.md @@ -8,7 +8,7 @@ Practical settings and habits to reduce token consumption, extend session qualit ## Recommended Settings -These are recommended defaults for most users. Power users can tune values further based on their workload — for example, setting `MAX_THINKING_TOKENS` lower for simple tasks or higher for complex architectural work. +Tune reasoning effort to your task and model: lower effort can reduce latency and cost, while higher effort suits complex work. Available levels and defaults depend on the model; see [Claude Code model configuration](https://code.claude.com/docs/en/model-config#adjust-effort-level). Add to your `~/.claude/settings.json`: @@ -16,7 +16,7 @@ Add to your `~/.claude/settings.json`: { "model": "sonnet", "env": { - "MAX_THINKING_TOKENS": "10000", + "CLAUDE_CODE_EFFORT_LEVEL": "medium", "CLAUDE_CODE_SUBAGENT_MODEL": "haiku" } } @@ -27,17 +27,21 @@ Add to your `~/.claude/settings.json`: | Setting | Default | Recommended | Effect | |---------|---------|-------------|--------| | `model` | opus | **sonnet** | Sonnet handles ~80% of coding tasks well. Switch to Opus with `/model opus` for complex reasoning. ~60% cost reduction. | -| `MAX_THINKING_TOKENS` | 31,999 | **10,000** | Extended thinking reserves up to 31,999 output tokens per request for internal reasoning. Reducing this cuts hidden cost by ~70%. Set to `0` to disable for trivial tasks. | +| `CLAUDE_CODE_EFFORT_LEVEL` | Model-dependent | **medium** | Sets adaptive reasoning effort. Adjust it for task complexity; supported levels depend on the model. | | `CLAUDE_CODE_SUBAGENT_MODEL` | _(inherits main)_ | **haiku** | Subagents (Task tool) run on this model. Haiku is ~80% cheaper and sufficient for exploration, file reading, and test running. | | `ECC_CONTEXT_MONITOR_COST_WARNINGS` | on | **off for subscription users** | Suppresses agent-facing API-rate estimate warnings while keeping context exhaustion, scope, and loop warnings. | +### Fixed thinking budgets + +`MAX_THINKING_TOKENS` applies to fixed-budget thinking. For Opus 4.6 or Sonnet 4.6, set `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` to use this mode before setting a positive budget. A positive value is ignored on adaptive reasoning models, so it does not provide a general cost cap. See the [environment variable reference](https://code.claude.com/docs/en/env-vars). + ### Community note on auto-compaction overrides Some recent Claude Code builds have community reports that `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` can only lower the compaction threshold, which means values below the default may compact earlier instead of later. If that happens in your setup, remove the override and rely on manual `/compact` plus ECC's `strategic-compact` guidance. See [Troubleshooting](./TROUBLESHOOTING.md). ### Toggling extended thinking -- **Alt+T** (Windows/Linux) or **Option+T** (macOS) — toggle on/off +- **Alt+T** (Windows/Linux) or **Option+T** (macOS) — toggle on/off where supported. Opus 5.5, Sonnet 5.5, and Fable models always think. - **Ctrl+O** — see thinking output (verbose mode) --- @@ -150,7 +154,7 @@ The `configure-ecc` install wizard could offer to set these environment variable /cost # Check spending # Environment variables (add to ~/.claude/settings.json "env" block) -MAX_THINKING_TOKENS=10000 +CLAUDE_CODE_EFFORT_LEVEL=medium CLAUDE_CODE_SUBAGENT_MODEL=haiku CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 ``` From a8980776d8a6f11cfb109e84eeb277c8d11e3679 Mon Sep 17 00:00:00 2001 From: Huanyi Xie <74809554+xiehuanyi@users.noreply.github.com> Date: Tue, 6 Oct 2026 19:22:07 +0300 Subject: [PATCH 3/3] docs: qualify effort settings by provider and model --- .cursor/rules/common-performance.md | 2 +- README.md | 7 ++++++- docs/token-optimization.md | 9 +++++++-- rules/common/performance.md | 2 +- 4 files changed, 15 insertions(+), 5 deletions(-) diff --git a/.cursor/rules/common-performance.md b/.cursor/rules/common-performance.md index 750bbb3a3..bc7b1b62b 100644 --- a/.cursor/rules/common-performance.md +++ b/.cursor/rules/common-performance.md @@ -43,7 +43,7 @@ rather than a fixed token budget. Available levels depend on the model. Control thinking via: - **Effort**: Use `/effort` in a session, `--effort ` at launch, or `CLAUDE_CODE_EFFORT_LEVEL`. Save a per-model level in `modelSettings` in `~/.claude/settings.json`; the older user-level `effortLevel` key does not apply to Opus 5.5 or newer models. - **Toggle**: Option+T (macOS) / Alt+T (Windows/Linux), or `alwaysThinkingEnabled` in settings. These cannot disable thinking on Opus 5.5, Sonnet 5.5, or Fable models. -- **Fixed budget**: A positive `MAX_THINKING_TOKENS` does not cap adaptive reasoning. On Opus 4.6 or Sonnet 4.6, set `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` to use a fixed budget with `MAX_THINKING_TOKENS`. +- **Fixed budget**: Claude Code ignores positive `MAX_THINKING_TOKENS` values on adaptive reasoning models. On Opus 4.6 or Sonnet 4.6, set `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` to use a fixed budget with `MAX_THINKING_TOKENS`. - **Verbose mode**: Ctrl+O to see thinking output See [Claude Code model configuration](https://code.claude.com/docs/en/model-config#adjust-effort-level) diff --git a/README.md b/README.md index b1b306ac9..dcb2df895 100644 --- a/README.md +++ b/README.md @@ -1725,10 +1725,15 @@ Add to `~/.claude/settings.json`: } ``` +The effort setting requires a model that supports effort controls. On Amazon Bedrock, +Google Cloud's Agent Platform, and Microsoft Foundry, the `sonnet` alias currently +resolves to Sonnet 4.5, which does not support effort controls. Select an effort-capable +model available from your provider, or omit `CLAUDE_CODE_EFFORT_LEVEL`. + | Setting | Default | Recommended | Impact | |---------|---------|-------------|--------| | `model` | opus | **sonnet** | ~60% cost reduction; handles 80%+ of coding tasks | -| `CLAUDE_CODE_EFFORT_LEVEL` | Model-dependent | **medium** | Controls adaptive reasoning depth; lower effort trades reasoning depth for latency and cost | +| `CLAUDE_CODE_EFFORT_LEVEL` | Model-dependent | **medium**, if supported | Controls adaptive reasoning depth on models that support effort controls; lower effort trades reasoning depth for latency and cost | | `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 95 | **50** | Compacts earlier, better quality in long sessions | | `ECC_CONTEXT_MONITOR_COST_WARNINGS` | on | **off for subscription users** | Suppresses agent-facing API-rate estimate warnings while keeping context/scope/loop warnings | diff --git a/docs/token-optimization.md b/docs/token-optimization.md index f3bf9259a..b6e00520e 100644 --- a/docs/token-optimization.md +++ b/docs/token-optimization.md @@ -22,12 +22,17 @@ Add to your `~/.claude/settings.json`: } ``` +The effort setting requires a model that supports effort controls. On Amazon Bedrock, +Google Cloud's Agent Platform, and Microsoft Foundry, the `sonnet` alias currently +resolves to Sonnet 4.5, which does not support effort controls. Select an effort-capable +model available from your provider, or omit `CLAUDE_CODE_EFFORT_LEVEL`. + ### What each setting does | Setting | Default | Recommended | Effect | |---------|---------|-------------|--------| | `model` | opus | **sonnet** | Sonnet handles ~80% of coding tasks well. Switch to Opus with `/model opus` for complex reasoning. ~60% cost reduction. | -| `CLAUDE_CODE_EFFORT_LEVEL` | Model-dependent | **medium** | Sets adaptive reasoning effort. Adjust it for task complexity; supported levels depend on the model. | +| `CLAUDE_CODE_EFFORT_LEVEL` | Model-dependent | **medium**, if supported | Sets adaptive reasoning effort on models that support effort controls. Adjust it for task complexity; supported levels depend on the model. | | `CLAUDE_CODE_SUBAGENT_MODEL` | _(inherits main)_ | **haiku** | Subagents (Task tool) run on this model. Haiku is ~80% cheaper and sufficient for exploration, file reading, and test running. | | `ECC_CONTEXT_MONITOR_COST_WARNINGS` | on | **off for subscription users** | Suppresses agent-facing API-rate estimate warnings while keeping context exhaustion, scope, and loop warnings. | @@ -154,7 +159,7 @@ The `configure-ecc` install wizard could offer to set these environment variable /cost # Check spending # Environment variables (add to ~/.claude/settings.json "env" block) -CLAUDE_CODE_EFFORT_LEVEL=medium +CLAUDE_CODE_EFFORT_LEVEL=medium # Only for models that support effort controls CLAUDE_CODE_SUBAGENT_MODEL=haiku CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 ``` diff --git a/rules/common/performance.md b/rules/common/performance.md index e8daa4174..db80f04d5 100644 --- a/rules/common/performance.md +++ b/rules/common/performance.md @@ -39,7 +39,7 @@ rather than a fixed token budget. Available levels depend on the model. Control thinking via: - **Effort**: Use `/effort` in a session, `--effort ` at launch, or `CLAUDE_CODE_EFFORT_LEVEL`. Save a per-model level in `modelSettings` in `~/.claude/settings.json`; the older user-level `effortLevel` key does not apply to Opus 5.5 or newer models. - **Toggle**: Option+T (macOS) / Alt+T (Windows/Linux), or `alwaysThinkingEnabled` in settings. These cannot disable thinking on Opus 5.5, Sonnet 5.5, or Fable models. -- **Fixed budget**: A positive `MAX_THINKING_TOKENS` does not cap adaptive reasoning. On Opus 4.6 or Sonnet 4.6, set `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` to use a fixed budget with `MAX_THINKING_TOKENS`. +- **Fixed budget**: Claude Code ignores positive `MAX_THINKING_TOKENS` values on adaptive reasoning models. On Opus 4.6 or Sonnet 4.6, set `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` to use a fixed budget with `MAX_THINKING_TOKENS`. - **Verbose mode**: Ctrl+O to see thinking output See [Claude Code model configuration](https://code.claude.com/docs/en/model-config#adjust-effort-level)