Skip to content

Commit db52081

Browse files
authored
Merge pull request anomalyco#210 from Warshoow/docs/token-optimization-guide
docs: add token optimization guide
2 parents e8f1250 + 6492190 commit db52081

2 files changed

Lines changed: 156 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -954,6 +954,26 @@ Agent Teams spawns multiple context windows. Each teammate consumes tokens indep
954954
955955
## ⚠️ Important Notes
956956
957+
### Token Optimization
958+
959+
Hitting daily limits? See the **[Token Optimization Guide](docs/token-optimization.md)** for recommended settings and workflow tips.
960+
961+
Quick wins:
962+
963+
```json
964+
// ~/.claude/settings.json
965+
{
966+
"model": "sonnet",
967+
"env": {
968+
"MAX_THINKING_TOKENS": "10000",
969+
"CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50",
970+
"CLAUDE_CODE_SUBAGENT_MODEL": "haiku"
971+
}
972+
}
973+
```
974+
975+
Use `/clear` between unrelated tasks, `/compact` at logical breakpoints, and `/cost` to monitor spending.
976+
957977
### Customization
958978
959979
These configs work for my workflow. You should:

‎docs/token-optimization.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# Token Optimization Guide
2+
3+
Practical settings and habits to reduce token consumption, extend session quality, and get more work done within daily limits.
4+
5+
> See also: `rules/common/performance.md` for model selection strategy, `skills/strategic-compact/` for automated compaction suggestions.
6+
7+
---
8+
9+
## Recommended Settings
10+
11+
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.
12+
13+
Add to your `~/.claude/settings.json`:
14+
15+
```json
16+
{
17+
"model": "sonnet",
18+
"env": {
19+
"MAX_THINKING_TOKENS": "10000",
20+
"CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50",
21+
"CLAUDE_CODE_SUBAGENT_MODEL": "haiku"
22+
}
23+
}
24+
```
25+
26+
### What each setting does
27+
28+
| Setting | Default | Recommended | Effect |
29+
|---------|---------|-------------|--------|
30+
| `model` | opus | **sonnet** | Sonnet handles ~80% of coding tasks well. Switch to Opus with `/model opus` for complex reasoning. ~60% cost reduction. |
31+
| `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. |
32+
| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 95 | **50** | Auto-compaction triggers when context reaches this % of capacity. Default 95% is too late — quality degrades before that. Compacting at 50% keeps sessions healthier. |
33+
| `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. |
34+
35+
### Toggling extended thinking
36+
37+
- **Alt+T** (Windows/Linux) or **Option+T** (macOS) — toggle on/off
38+
- **Ctrl+O** — see thinking output (verbose mode)
39+
40+
---
41+
42+
## Model Selection
43+
44+
Use the right model for the task:
45+
46+
| Model | Best for | Cost |
47+
|-------|----------|------|
48+
| **Haiku** | Subagent exploration, file reading, simple lookups | Lowest |
49+
| **Sonnet** | Day-to-day coding, reviews, test writing, implementation | Medium |
50+
| **Opus** | Complex architecture, multi-step reasoning, debugging subtle issues | Highest |
51+
52+
Switch models mid-session:
53+
54+
```
55+
/model sonnet # default for most work
56+
/model opus # complex reasoning
57+
/model haiku # quick lookups
58+
```
59+
60+
---
61+
62+
## Context Management
63+
64+
### Commands
65+
66+
| Command | When to use |
67+
|---------|-------------|
68+
| `/clear` | Between unrelated tasks. Stale context wastes tokens on every subsequent message. |
69+
| `/compact` | At logical task breakpoints (after planning, after debugging, before switching focus). |
70+
| `/cost` | Check token spending for the current session. |
71+
72+
### Strategic compaction
73+
74+
The `strategic-compact` skill (in `skills/strategic-compact/`) suggests `/compact` at logical intervals rather than relying on auto-compaction, which can trigger mid-task. See the skill's README for hook setup instructions.
75+
76+
**When to compact:**
77+
- After exploration, before implementation
78+
- After completing a milestone
79+
- After debugging, before continuing with new work
80+
- Before a major context shift
81+
82+
**When NOT to compact:**
83+
- Mid-implementation of related changes
84+
- While debugging an active issue
85+
- During multi-file refactoring
86+
87+
### Subagents protect your context
88+
89+
Use subagents (Task tool) for exploration instead of reading many files in your main session. The subagent reads 20 files but only returns a summary — your main context stays clean.
90+
91+
---
92+
93+
## MCP Server Management
94+
95+
Each enabled MCP server adds tool definitions to your context window. The README warns: **keep under 10 enabled per project**.
96+
97+
Tips:
98+
- Run `/mcp` to see active servers and their context cost
99+
- Prefer CLI tools when available (`gh` instead of GitHub MCP, `aws` instead of AWS MCP)
100+
- Use `disabledMcpServers` in project config to disable servers per-project
101+
- The `memory` MCP server is configured by default but not used by any skill, agent, or hook — consider disabling it
102+
103+
---
104+
105+
## Agent Teams Cost Warning
106+
107+
[Agent Teams](https://code.claude.com/docs/en/agent-teams) (experimental) spawns multiple independent context windows. Each teammate consumes tokens separately.
108+
109+
- Only use for tasks where parallelism adds clear value (multi-module work, parallel reviews)
110+
- For simple sequential tasks, subagents (Task tool) are more token-efficient
111+
- Enable with: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in settings
112+
113+
---
114+
115+
## Future: configure-ecc Integration
116+
117+
The `configure-ecc` install wizard could offer to set these environment variables during setup, with explanations of the cost tradeoffs. This would help new users optimize from day one rather than discovering these settings after hitting limits.
118+
119+
---
120+
121+
## Quick Reference
122+
123+
```bash
124+
# Daily workflow
125+
/model sonnet # Start here
126+
/model opus # Only for complex reasoning
127+
/clear # Between unrelated tasks
128+
/compact # At logical breakpoints
129+
/cost # Check spending
130+
131+
# Environment variables (add to ~/.claude/settings.json "env" block)
132+
MAX_THINKING_TOKENS=10000
133+
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50
134+
CLAUDE_CODE_SUBAGENT_MODEL=haiku
135+
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
136+
```

0 commit comments

Comments
 (0)