diff --git a/.cursor/rules/common-performance.md b/.cursor/rules/common-performance.md index ef4114025..bc7b1b62b 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**: 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) +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/README.md b/README.md index 67f4bf63b..a5477d222 100644 --- a/README.md +++ b/README.md @@ -1828,20 +1828,27 @@ 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" } } ``` +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 | -| `MAX_THINKING_TOKENS` | 31,999 | **10,000** | ~70% reduction in hidden thinking cost per request | +| `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 | +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..b6e00520e 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,28 +16,37 @@ Add to your `~/.claude/settings.json`: { "model": "sonnet", "env": { - "MAX_THINKING_TOKENS": "10000", + "CLAUDE_CODE_EFFORT_LEVEL": "medium", "CLAUDE_CODE_SUBAGENT_MODEL": "haiku" } } ``` +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. | -| `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**, 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. | +### 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 +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) -MAX_THINKING_TOKENS=10000 +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 0a2f22977..db80f04d5 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**: 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) +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