tools-only Context Efficiency: The Core Principle
Why Navigator Exists
The Problem I Kept Hitting
I was working on a feature in my project. AI coding session going great—Claude understood the architecture, made smart suggestions, everything clicked.
Then exchange 6 happened.
Claude forgot a function I'd just written. Exchange 7, it hallucinated a class that didn't exist. Exchange 8, session crashed. "Context limit reached."
I checked the stats: 150,000 tokens loaded. I'd used maybe 8,000.
I was wasting 94% of my context window on documentation I never needed.
Why This Kept Happening
This wasn't a bug. This was my workflow.
Every AI session, same pattern:
- Load all project docs at start ("just in case")
- Context fills with everything
- AI gets overwhelmed by noise
- Forgets recent changes (signal lost in noise)
- Session dies
- Start over
- Repeat
The default approach—load everything upfront—was the problem.
Not the tools. Not the AI. My workflow.
The Realization
I was using AI wrong.
Bulk loading mindset:
- "Better to have it all available"
- "I might need any of this"
- "Loading everything is safer"
Result: 70-90% waste. Every session.
Then I read Anthropic's context engineering docs.
Two images changed everything:
Context Engineering vs Prompt Engineering
Prompt engineering: Single query → optimize the prompt Context engineering: Multi-turn agent → curate the context
From their docs:
Available context:
├── Many docs
├── Many tools
├── Memory files
└── Domain knowledge
Curated context (what actually loads):
├── Doc 1 ✓
├── Doc 2 ✓
└── Tool 1 ✓
NOT everything. Strategic selection.
This was the answer.
The Principle
Load What You Need, When You Need It
Not "load everything just in case." Not "better safe than sorry."
Strategic curation beats bulk loading.
How It Works
Traditional approach (bulk loading):
Session start:
→ Load all docs (150k tokens)
→ Context 75% full immediately
→ 50k tokens left for actual work
→ Session dies in 5-7 exchanges
Context engineering approach (Navigator):
Session start:
→ Load navigator/index (2k tokens)
→ Load current task context (3k tokens)
→ 195k tokens available for work
As you work:
→ Need system architecture? Load it (5k)
→ Need integration docs? Load them (3k)
→ Need SOP? Load it (2k)
Progressive, strategic, on-demand.
Result: 92% of context available for actual work.
The Implementation
Navigator's Curation Strategy
Your project has documentation. Lots of it.
Your .agent/ directory:
├── system/ (~25k tokens)
│ ├── architecture.md
│ ├── database.md
│ └── api-design.md
├── tasks/ (~30k tokens)
│ ├── TASK-01.md
│ ├── TASK-02.md
│ └── ...
├── sops/ (~20k tokens)
│ ├── debugging.md
│ ├── deployment.md
│ └── ...
└── learning/ (~10k tokens)
Total available: ~85k tokens
Bulk loading: Load all 85k at session start Result: Context 42% full before you start working
Navigator's curation: Load strategically
Session start:
├── DEVELOPMENT-README.md (~2k) ✓ Navigator/index
└── Current task doc (~3k) ✓ What you're working on
Total loaded: ~5k tokens (94% savings)
Context usage: 2.5% (197.5k available for work)
As you work, load more only if needed:
- Implementing API? Load
system/api-design.md(5k) - Hit a bug? Load relevant SOP (2k)
- Need deployment info? Load it then (3k)
Maximum session: ~15k tokens loaded (still 92% savings)
The Proof
Real Metrics (Not Estimates)
Your project (typical):
- Documentation available: 100-150k tokens
- Navigator loads: 10-15k tokens
- Savings: 85-92%
Verified via OpenTelemetry, not file size guesses.
From TASK-06 (Navigator's own metrics):
Documentation available: 150,000 tokens
Loaded this session: 12,000 tokens
Tokens saved: 138,000 tokens (92%)
Cache efficiency: 100%
(Loaded once, reused from cache 10.5x)
This is context engineering in action.
Token Budget Mental Model
Think of your context window like a workspace:
200k Token Context Window
Without Navigator (bulk loading):
┌─────────────────────────────────────────┐
│ System prompt & tools: 50k (25%) │ Fixed overhead
├─────────────────────────────────────────┤
│ All docs loaded: 100k (50%) │ ← Waste
├─────────────────────────────────────────┤
│ Available for work: 50k (25%) │ ← Cramped
└─────────────────────────────────────────┘
Result: 75% full before you start
Sessions die in 5-7 exchanges
With Navigator (strategic curation):
┌─────────────────────────────────────────┐
│ System prompt & tools: 50k (25%) │ Fixed overhead
├─────────────────────────────────────────┤
│ Navigator + current task: 12k (6%) │ ← Curated
├─────────────────────────────────────────┤
│ Available for work: 138k (69%) │ ← Spacious
└─────────────────────────────────────────┘
Result: 31% used, 69% available for work
Sessions last 20+ exchanges
2.75x more space for actual work.
The Decision Framework
When to Load What
Always load:
- Navigator/index (
DEVELOPMENT-README.md) - 2k tokens- Shows what exists, where to find it
- Guides navigation to relevant docs
Load for current work:
- Active task documentation - 3-5k tokens
- Implementation plan for feature you're building
- Context specific to current work
Load as needed:
System architecture - 5-10k tokens
- Only when implementing features touching core systems
- Not every session needs this
SOPs (procedures) - 2-3k tokens each
- Only when you hit specific scenarios
- Debugging? Load debugging SOP
- Deploying? Load deployment SOP
Progressive refinement:
- Start with summary/overview
- Drill down only if needed
- Don't load details upfront
When to Use Agents vs Manual Reads
Part of context efficiency: Use agents for exploration.
Use Navigator's Task Agent When:
Multi-file searches:
- ❌ Manual: Read 20 files (80k tokens loaded)
- ✅ Agent: Reads, summarizes, returns relevant parts (8k tokens)
- Savings: 90%
Understanding unfamiliar code:
- ❌ Manual: Read everything to find pattern
- ✅ Agent: Searches, identifies pattern, explains
- Savings: 70%
Code pattern discovery:
- ❌ Manual: Sample files one by one
- ✅ Agent: Finds representative examples
- Savings: 75%
Use Manual Read When:
Known specific file:
- You know exactly what you need
- Single file, specific location
- Agent would be overkill
1-2 files already loaded:
- Context already contains what you need
- No additional loading required
Small targeted edits:
- Working with current context
- No exploration needed
Progressive Refinement Pattern
From Anthropic's context engineering: Fetch metadata first, details on-demand.
Example: Figma Design Review
Bulk approach:
1. Fetch entire design file (150k tokens)
2. Parse everything
3. Extract components
4. Map to design system
Token cost: 150k
Time: 15 minutes
Progressive refinement (Navigator v3.4.0):
1. Fetch metadata (12k tokens)
→ File structure, component names, high-level hierarchy
2. Analyze metadata
→ Identify which components need details
3. Fetch details only for relevant components (additional 5-8k)
→ Full properties only where needed
Token cost: 20k (87% savings)
Time: 5 minutes (67% faster)
Apply this pattern everywhere:
- Load summaries before full docs
- Check overviews before implementation details
- Fetch structure before content
Context Efficiency in Practice
Real Workflows
Feature implementation:
Load:
├── Navigator (2k)
├── Task doc (3k)
└── Relevant system doc (5k)
Total: 10k tokens
Session: Implements feature in 15 exchanges
Context at end: 45% (comfortable)
Bug fix:
Load:
├── Navigator (2k)
├── Debugging SOP (2k)
└── Relevant code context (from agent search, 5k)
Total: 9k tokens
Session: Finds and fixes bug in 8 exchanges
Context at end: 30% (plenty of room)
Architecture design:
Load:
├── Navigator (2k)
├── System architecture (8k)
├── Integration docs (5k)
└── Design patterns SOP (3k)
Total: 18k tokens
Session: Designs new system in 20 exchanges
Context at end: 55% (still functional)
Even heavy sessions stay efficient.
The Broader Principle
Context efficiency isn't just about Navigator. It's about using AI right.
Right Tool for the Job
From v3.4.0 (Figma integration) lesson:
LLMs are brilliant at:
- Semantic understanding
- Natural language
- Code generation
- Contextual decisions
LLMs are terrible at:
- Deterministic parsing (use Python)
- Structure traversal (use traditional code)
- Data normalization (use scripts)
- Schema validation (use proper parsers)
Navigator applies this:
- Python/bash for deterministic operations (doc loading, file finding)
- LLM for semantic work (understanding, generating, deciding)
You wouldn't use regex to parse HTML. Don't use bulk loading for AI context.
Measuring Context Efficiency
Navigator tracks your efficiency. Run "Show me my session statistics":
╔══════════════════════════════════════════════════════╗
║ NAVIGATOR EFFICIENCY REPORT ║
╚══════════════════════════════════════════════════════╝
📊 TOKEN USAGE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Your project documentation: 150,000 tokens
Loaded this session: 12,000 tokens
Tokens saved: 138,000 tokens (92% ↓)
💾 CACHE PERFORMANCE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Cache efficiency: 100% (perfect)
📈 SESSION METRICS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Context usage: 35% (excellent)
Efficiency score: 94/100 (excellent)
⏱️ TIME SAVED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Estimated time saved: ~42 minutes
These are YOUR metrics. Your project. Your savings.
Context Efficiency Score
Navigator calculates efficiency (0-100):
Formula:
- Token savings (40 points): 85%+ savings = 40 points
- Cache efficiency (30 points): 100% = 30 points
- Context usage (30 points): <40% usage = 30 points
Score interpretation:
- 90-100: Excellent - Optimal Navigator usage
- 80-89: Good - Minor improvements possible
- 70-79: Fair - Review lazy-loading strategy
- <70: Needs improvement - Check anti-patterns
Starting Your Context-Efficient Workflow
Every Session Begins:
"Start my Navigator session"
This loads:
Navigator/index (DEVELOPMENT-README.md) - 2k tokens
- Shows what documentation exists
- Guides you to relevant docs
- Decision framework for what to load
Current task context (if configured with PM tools) - 3k tokens
- What you're working on right now
- Implementation plan
- Relevant context
Nothing else yet - 195k tokens available
As You Work:
Need to understand architecture?
- Navigate to
system/architecture.md - Loads on-demand (5k)
Hit a deployment issue?
- Navigate to
sops/deployment.md - Loads when needed (2k)
Need to search codebase?
- Use Task agent (curated search)
- Returns relevant parts only (8k vs 80k manual reading)
Everything is on-demand. Nothing upfront.
The Core Insight
Context engineering is curation.
From Anthropic's docs (literally):
Possible context: Curated context:
├── Doc 1 ├── Doc 1 ✓
├── Doc 2 ├── Doc 2 ✓
├── Doc 3 └── Tool 1 ✓
├── Doc 4
├── Tool 1
└── Tool 2
Load strategically, not everything.
Navigator implements this for your codebase.
Not "here's a feature that reduces tokens." This is "here's context engineering, proven."
Learn More
Understand failure modes: → Read Anti-Patterns - Common mistakes
See success patterns: → Read Patterns - What works and why
Apply to your work:
→ Read .agent/learning/ - Guides and examples
Start now:
"Start my Navigator session"
Summary
The Problem
Bulk loading wastes 70-90% of context window
The Solution
Context engineering: Strategic curation over bulk loading
The Proof
92% token savings, verified via OpenTelemetry
The Principle
Load what you need, when you need it
The Practice
Navigator implements context engineering for your codebase
This is why Navigator exists.
Not to save tokens. To teach context efficiency.
Ready to start? → "Start my Navigator session"