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] 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
 ```