Token Optimization

Token Optimization Skill

When This Skill Activates

This skill provides methodology for efficient token usage:

• Long-running sessions approaching context limits
• Large codebase exploration
• Multiple file modifications
• Complex multi-step tasks

Token Awareness

Context Budget

• Total context: ~200K tokens
• Practical limit: ~160K (leave buffer)
• Compact at: 70% capacity
• Avoid complex work at: >80% capacity

Token Costs (Approximate)

Optimization Strategies

1. Progressive Disclosure

Instead of loading everything upfront:

Bad:  Read all 50 files at once
Good: Read index → identify relevant → read specific

2. Targeted Search

Use efficient search patterns:

Bad:  Read entire directory tree
Good: Glob pattern → Grep specific → Read matches

3. Minimal Context

Include only what's needed:

Bad:  Include entire file for small change
Good: Include function + surrounding context

4. Structured Summaries

For long outputs:

Bad:  Full test output (10K tokens)
Good: Summary + key failures (500 tokens)

5. Timely Compaction

Monitor and compact proactively:

Bad:  Wait for "Context low" warning
Good: Compact at 70% after task completion

MCP Token Management

Problem: MCP Server Token Drain

MCP tools can consume 30-60K tokens before conversation starts.

Solution: Selective Loading

• Only enable needed MCP servers per session
• Disable unused servers when not needed
• Use claude mcp list to audit

Memory Server Strategy

Compaction Strategy

Pre-Compaction Checklist

1. ✅ Critical context saved to memory MCP
2. ✅ Important decisions documented
3. ✅ Current task state captured
4. ✅ Key file paths noted

Post-Compaction Recovery

1. Load context from memory MCP
2. Re-read critical files if needed
3. Check decision-audit.jsonl for context
4. Resume task from documented state

Code Patterns

Efficient File Operations

# Bad: Read all then filter
for f in all_files:
    content = read(f)
    if "pattern" in content:
        process(f)

# Good: Search first then read
matches = grep("pattern", all_files)
for f in matches:
    content = read(f)
    process(f)

Efficient Updates

# Bad: Full file replacement
content = read(file)
new_content = content.replace(old, new)
write(file, new_content)

# Good: Targeted edit
edit(file, old_string=old, new_string=new)

Efficient Exploration

# Bad: Deep recursive exploration
explore_all_directories(root)

# Good: Breadth-first with limits
list_top_level(root)
identify_relevant_dirs()
explore_targeted(relevant_only)

Session Management

Long Session Strategy

1. Start: Load minimal context
2. Work: Add context as needed
3. Checkpoint: Save state periodically
4. Compact: At 70% or task completion
5. Recover: Restore from checkpoint

Task Batching

Bad:  One massive continuous session
Good: Multiple focused sessions with clear handoffs

Integration with Hooks

Pre-Compact Hook

Automatically triggered when context low:

• Backs up transcript
• Creates recovery index
• Logs compaction event

Session Start Hook

Restores context efficiently:

• Loads minimal git status
• Checks for recovery context
• Provides continuation hints

Metrics to Monitor

Track these for optimization:

• Session length before compaction
• Files read per task
• Tool calls per operation
• Recovery success rate