# Token Optimization Best Practices

## Context Window Budget

**Total Available:** 200,000 tokens

### Budget Allocation

| Component | Target | Max | Notes |
|-----------|--------|-----|-------|
| System prompt | ~5,000 | Fixed | Claude Code internal |
| CLAUDE.md | 2,000 | 3,000 | Under your control |
| MCP Servers | 5,000 | 10,000 | With Tool Search enabled |
| Skills metadata | 500 | 1,000 | Description + frontmatter only |
| **Working space** | **>140,000** | — | **Goal: 70%+ available** |

### Why 70%+ Available?

- Complex tasks need context for code, files, conversation
- Long sessions accumulate context
- Safety buffer prevents truncation

## MCP Server Optimization

### serverInstructions (CRITICAL)

Every MCP server MUST have `serverInstructions` for Tool Search to work:

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-playwright"],
      "serverInstructions": "Browser automation. Use for: SEO audits, screenshots, page analysis. Keywords: browser, page, DOM, screenshot"
    }
  }
}
```

**Pattern:** `[What it does]. Use for: [use case 1], [use case 2]. Keywords: [keyword1], [keyword2]`

### Load Strategies

| Strategy | When to Use | Example Servers |
|----------|-------------|-----------------|
| **always** | Essential for daily work | Playwright, Notion, Filesystem |
| **lazy** | Occasionally needed | GitHub, PostgreSQL, Slack |
| **disable** | Rarely used or token-heavy | Zapier (25K+ tokens) |

### Token Estimates by Server

| Server | Approx. Tokens | Strategy |
|--------|----------------|----------|
| Playwright | 13,500 | always |
| Notion | 5,000 | always |
| GitHub | 18,000 | lazy |
| PostgreSQL | 8,000 | lazy |
| Zapier | 25,000+ | disable |
| Memory | 3,000 | lazy |
| Filesystem | 4,000 | always |

## CLAUDE.md Optimization

### Size Limits

- **Lines:** Under 200
- **Tokens:** Under 3,000 (~2,300 words)

### What to Include

1. **Role context** (1-2 sentences)
2. **Output preferences** (format, language)
3. **Domain standards** (brief, essential only)
4. **Available commands** (reference list)
5. **Quality checklist** (3-5 items)

### What to Exclude

- Self-descriptions ("You are Claude...")
- Information Claude already knows
- Verbose explanations
- Long code examples (use skills instead)
- Duplicate information

### Optimal Structure

```markdown
# Project Context

## Role
[1-2 sentences]

## Preferences
- Output: [format]
- Language: [preference]

## Standards
### Domain 1
- [Key point 1]
- [Key point 2]

## Commands
- /command1: [brief description]
- /command2: [brief description]

## Checklist
- [ ] Item 1
- [ ] Item 2
```

## Session Management

### During Work

1. **Check context:** Run `/context` before complex tasks
2. **Compact early:** Run `/compact` at 70% usage
3. **Clear between tasks:** Run `/clear` for unrelated work

### Weekly Maintenance

1. Run `/doctor` for MCP health
2. Review command usage patterns
3. Update CLAUDE.md with new patterns
4. Check for unused extensions

### Monthly Audit

1. Run full settings audit
2. Review and prune unused MCP servers
3. Update serverInstructions
4. Check for new optimization opportunities

## Quick Diagnostics

### High Token Usage Signs

- Slow response times
- Context getting truncated
- Claude "forgetting" earlier context

### Common Fixes

| Issue | Fix |
|-------|-----|
| CLAUDE.md too long | Move details to skills/references |
| MCP missing instructions | Add serverInstructions |
| Too many always-loaded MCPs | Switch some to lazy |
| Unused extensions | Remove or disable |

## Commands Reference

| Command | Purpose |
|---------|---------|
| `/context` | Check current context usage |
| `/compact` | Compress context |
| `/clear` | Clear conversation |
| `/doctor` | Check MCP server health |
| `/settings-audit` | Run this skill's audit |