# Claude Code Settings Optimizer

Self-audit and optimize Claude Code configuration for maximum token efficiency and performance.

## Core Focus

1. **Token Budget Management** - Keep baseline under 30% of 200K context
2. **MCP Tool Loading Strategy** - Essential tools always, others lazy-loaded
3. **CLAUDE.md Optimization** - Concise, structured, under 200 lines
4. **Context Preservation** - Maintain original prompt context throughout session

## Quick Commands

```bash
# Run full audit
python3 scripts/run_audit.py

# Check token usage only
python3 scripts/analyze_tokens.py

# Auto-fix with preview
python3 scripts/auto_fix.py

# Apply fixes
python3 scripts/auto_fix.py --apply
```

## Audit Scope

### 1. Token Usage Analysis

| Component | Target | Max | Action if Exceeded |
|-----------|--------|-----|-------------------|
| CLAUDE.md | 2,000 | 3,000 | Compress/split |
| MCP Servers | 5,000 | 10,000 | Enable Tool Search, add serverInstructions |
| Skills metadata | 500 | 1,000 | Reduce descriptions |
| **Working space** | **>140,000** | — | Goal: 70%+ available |

### 2. MCP Server Strategy

**Load Strategy Classification:**

| Strategy | Criteria | Action |
|----------|----------|--------|
| `always` | Essential for daily work (Playwright, Notion) | Keep loaded |
| `lazy` | Occasionally needed (GitHub, Slack) | Load on demand |
| `disable` | Rarely used or token-heavy (Zapier 50+ tools) | Turn off |

**Critical Check:** Every MCP server MUST have `serverInstructions` for Tool Search to work efficiently.

### 3. CLAUDE.md Health

Check for:
- Line count (warn >200)
- Token estimate (warn >3,000)
- Structure quality (headers, lists vs wall of text)
- Redundant information
- Information Claude already knows (don't repeat)

### 4. Extension Efficiency

- Commands: Has frontmatter? Under 100 lines?
- Skills: SKILL.md present? Under 500 lines?
- Agents: Tools restricted appropriately?

## Output Report

```markdown
# Claude Code Settings Audit

## Token Budget
- Baseline usage: X / 200,000 (Y%)
- Available for work: Z tokens

## Health Status
- Overall: [Good/Needs Attention/Critical]
- MCP Servers: X configured, Y missing instructions
- CLAUDE.md: X lines, ~Y tokens

## Findings
### Critical (must fix)
### Warnings (should fix)
### Passing (good)

## Recommendations
[Prioritized action items]
```

## Auto-Fix Capabilities

Safe fixes applied automatically (with backup):
- Add `serverInstructions` to MCP servers
- Add frontmatter to commands missing it
- Suggest CLAUDE.md compression

Manual review required:
- Disabling MCP servers
- Restructuring CLAUDE.md content
- Removing unused extensions

## Best Practices

### Token Optimization Principles

1. **CLAUDE.md**: Only include what Claude doesn't already know
2. **MCP Servers**: Use `serverInstructions` for Tool Search discovery
3. **Skills**: Keep SKILL.md brief, details in `references/`
4. **Context**: Run `/compact` at 70% usage, `/clear` between unrelated tasks

### Ideal Configuration

```
Context Budget: 200,000 tokens
├── System prompt: ~5,000 (fixed)
├── CLAUDE.md: ~2,000 (your control)
├── MCP tools: ~5,000 (with Tool Search)
├── Skills: ~500 (metadata only)
└── Available: ~187,500 (93.75%)
```