Skip to content

Commit 4209421

Browse files
committed
docs: add token optimization guide with recommended settings (anomalyco#175)
Adds a comprehensive Token Optimization section to the README with: - Recommended settings (model, MAX_THINKING_TOKENS, AUTOCOMPACT_PCT) - Daily workflow commands table (/model, /clear, /compact, /cost) - Strategic compaction guidance (when to compact vs not) - Context window management (MCP tool description costs) - Agent Teams cost warning
1 parent f56fb33 commit 4209421

1 file changed

Lines changed: 63 additions & 7 deletions

File tree

‎README.md‎

Lines changed: 63 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -325,6 +325,7 @@ everything-claude-code/
325325
| |-- saas-nextjs-CLAUDE.md # Real-world SaaS (Next.js + Supabase + Stripe)
326326
| |-- go-microservice-CLAUDE.md # Real-world Go microservice (gRPC + PostgreSQL)
327327
| |-- django-api-CLAUDE.md # Real-world Django REST API (DRF + Celery)
328+
| |-- rust-api-CLAUDE.md # Real-world Rust API (Axum + SQLx + PostgreSQL) (NEW)
328329
|
329330
|-- mcp-configs/ # MCP server configurations
330331
| |-- mcp-servers.json # GitHub, Supabase, Vercel, Railway, etc.
@@ -883,18 +884,73 @@ These configs are battle-tested across multiple production applications.
883884
884885
---
885886
886-
## ⚠️ Important Notes
887+
## Token Optimization
888+
889+
Claude Code usage can be expensive if you don't manage token consumption. These settings significantly reduce costs without sacrificing quality.
890+
891+
### Recommended Settings
892+
893+
Add to `~/.claude/settings.json`:
894+
895+
```json
896+
{
897+
"model": "sonnet",
898+
"env": {
899+
"MAX_THINKING_TOKENS": "10000",
900+
"CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50"
901+
}
902+
}
903+
```
904+
905+
| Setting | Default | Recommended | Impact |
906+
|---------|---------|-------------|--------|
907+
| `model` | opus | **sonnet** | ~60% cost reduction; handles 80%+ of coding tasks |
908+
| `MAX_THINKING_TOKENS` | 31,999 | **10,000** | ~70% reduction in hidden thinking cost per request |
909+
| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 95 | **50** | Compacts earlier — better quality in long sessions |
910+
911+
Switch to Opus only when you need deep architectural reasoning:
912+
```
913+
/model opus
914+
```
915+
916+
### Daily Workflow Commands
917+
918+
| Command | When to Use |
919+
|---------|-------------|
920+
| `/model sonnet` | Default for most tasks |
921+
| `/model opus` | Complex architecture, debugging, deep reasoning |
922+
| `/clear` | Between unrelated tasks (free, instant reset) |
923+
| `/compact` | At logical task breakpoints (research done, milestone complete) |
924+
| `/cost` | Monitor token spending during session |
925+
926+
### Strategic Compaction
927+
928+
The `strategic-compact` skill (included in this plugin) suggests `/compact` at logical breakpoints instead of relying on auto-compaction at 95% context. See `skills/strategic-compact/SKILL.md` for the full decision guide.
929+
930+
**When to compact:**
931+
- After research/exploration, before implementation
932+
- After completing a milestone, before starting the next
933+
- After debugging, before continuing feature work
934+
- After a failed approach, before trying a new one
935+
936+
**When NOT to compact:**
937+
- Mid-implementation (you'll lose variable names, file paths, partial state)
887938
888939
### Context Window Management
889940
890-
**Critical:** Don't enable all MCPs at once. Your 200k context window can shrink to 70k with too many tools enabled.
941+
**Critical:** Don't enable all MCPs at once. Each MCP tool description consumes tokens from your 200k window, potentially reducing it to ~70k.
942+
943+
- Keep under 10 MCPs enabled per project
944+
- Keep under 80 tools active
945+
- Use `disabledMcpServers` in project config to disable unused ones
946+
947+
### Agent Teams Cost Warning
891948
892-
Rule of thumb:
893-
- Have 20-30 MCPs configured
894-
- Keep under 10 enabled per project
895-
- Under 80 tools active
949+
Agent Teams spawns multiple context windows. Each teammate consumes tokens independently. Only use for tasks where parallelism provides clear value (multi-module work, parallel reviews). For simple sequential tasks, subagents are more token-efficient.
896950
897-
Use `disabledMcpServers` in project config to disable unused ones.
951+
---
952+
953+
## ⚠️ Important Notes
898954
899955
### Customization
900956

0 commit comments

Comments
 (0)