Context Engineering

Quick Reference

Key Metrics

• Token utilization: Warning at 70%, trigger optimization at 80%
• Token variance: Explains 80% of agent performance variance
• Multi-agent cost: ~15x single agent baseline
• Compaction target: 50-70% reduction, <5% quality loss
• Cache hit target: 70%+ for stable workloads
• tilth cost reduction: ~40% cost/correct answer (benchmarked across 160 runs on Sonnet/Opus/Haiku)

Four-Bucket Strategy

1. Write: Save context externally (scratchpads, files)
2. Select: Pull only relevant context (retrieval, filtering). Use tilth_search for definition-first search (avoids grep token waste). Use tilth_read for auto-outlined file reading (skips large files automatically).
3. Compress: Reduce tokens while preserving info (summarization). tilth session dedup shows [shown earlier] for previously expanded definitions.
4. Isolate: Split across sub-agents (partitioning)

Anti-Patterns

• Exhaustive context over curated context
• Critical info in middle positions
• No compaction triggers before limits
• Single agent for parallelizable tasks
• Tools without clear descriptions

Guidelines

1. Place critical info at beginning/end of context
2. Implement compaction at 70-80% utilization
3. Use sub-agents for context isolation, not role-play
4. Design tools with 4-question framework (what, when, inputs, returns)
5. Optimize for tokens-per-task, not tokens-per-request
6. Validate with probe-based evaluation
7. Monitor KV-cache hit rates in production
8. Start minimal, add complexity only when proven necessary

Runtime Awareness

The system automatically injects usage awareness via PostToolUse hook:

<usage-awareness>
Claude Usage Limits: 5h=45%, 7d=32%
Context Window Usage: 67%
</usage-awareness>

Thresholds:

• 70%: WARNING - consider optimization/compaction
• 90%: CRITICAL - immediate action needed

Data Sources:

• Usage limits: Anthropic OAuth API (https://api.anthropic.com/api/oauth/usage)
• Context window: Statusline temp file (/tmp/ck-context-{session_id}.json)

These capabilities are built into the agent workflow — no external scripts needed.

Hard Gate

• Context usage checked before adding new skills/files
• High-signal content prioritized over exhaustive content
• No duplicate information across loaded skills

Done Condition

Context optimized + token budget monitored + relevant references loaded just-in-time