Context Optimizer
Optimize AI context loading for efficient token usage and focused development sessions.
When to Use
- Working with large codebases (>50 files)
- Context window approaching limits
- User mentions "context", "token", "optimize"
- Starting a new development session
Context Scoring
| Factor |
Weight |
Description |
| Direct relevance |
40% |
Directly related to current task |
| Dependency chain |
25% |
Required by relevant files |
| Recent access |
20% |
Recently read or modified |
| Reference frequency |
15% |
Often referenced in codebase |
Optimization Strategies
| Strategy |
Load Scope |
Token Savings |
| A: Essential Only |
Modified files + type defs + immediate deps |
60-80% |
| B: Focused Context |
Working files + 1-level deps + docs + config |
40-60% |
| C: Summarized |
Full working files + summaries + index |
30-50% |
Document Priority Loading
| Priority |
Files |
When |
| 1 (Always) |
docs/CONTEXT.md, docs/PROGRESS.md |
Every session |
| 2 (Phase) |
docs/phases/phase-N/SPEC.md, TASKS.md |
Phase work |
| 3 (On-Demand) |
docs/PRD.md, docs/TECH-SPEC.md, src/**/* |
As needed |
Token Budget Guidelines
| Session Type |
Budget |
Loading Strategy |
| Quick check |
~2K |
CONTEXT.md + PROGRESS.md |
| Standard dev |
~10K |
CONTEXT + PROGRESS + active files |
| Deep dive |
~30K |
All docs + relevant source |
| Full context |
~50K+ |
Complete project load |
Incremental Context Protocol
Turn-by-turn progressive loading to minimize initial token cost.
Loading Sequence
| Turn |
Load |
Tokens |
Purpose |
| 1 |
AGENTS.md (lean) + MANIFEST.md + CONTEXT.md |
~1.1K |
User intent detection |
| 2 |
Task-specific files (TASKS.md row + source) |
+2-3K |
Intent-scoped work |
| 3+ |
On-demand (SPEC, PRD, etc.) |
+varies |
As referenced |
Note: auto_load_phase_docs deferred until Turn 2.
Expansion Triggers
| User Intent |
Load Target |
Budget Impact |
| Phase 작업 |
+phase docs (SPEC, TASKS) |
+2-3K |
| 아키텍처 논의 |
+TECH-SPEC + adjacent phase SPECs |
+5-8K |
| 코드 리뷰 |
+PRD (requirements) + CHECKLIST |
+3-5K |
| 전체 현황 |
+PROGRESS + all phase summaries |
+5-10K |
settings.json Configuration
{
"context-optimizer": {
"loading_strategy": "incremental",
"initial_budget": 800,
"expansion_triggers": {
"phase_work": "+phase_docs",
"architecture": "+tech_spec+adjacent_phases",
"review": "+prd+checklist",
"full_status": "+progress+all_phase_summaries"
}
}
}
Task-Scoped Context Boundary
| Level |
Scope |
Tokens |
Contents |
| 1: Task-Active (default) |
Single task |
~3-6K |
CONTEXT.md + Task row + source + direct deps |
| 2: Phase-Full |
Full phase |
~8-10K |
Level 1 + SPEC.md + CHECKLIST.md |
| 3: Cross-Phase |
Architecture |
~12-15K |
Level 2 + adjacent SPEC.md + TECH-SPEC sections |
Task Context Format
## Task T2-03 Context
Source: docs/phases/phase-2/TASKS.md (row 3 only)
| ID | Task | Status | Priority | Est |
|----|------|--------|----------|-----|
| T2-03 | API endpoint 구현 | 🔄 | P0 | 3h |
Related files: server/src/routes/api.ts, server/src/models/schema.ts
Dependencies: T2-01 (DB schema), T2-02 (auth middleware)
Session Checkpoint Protocol
Auto-save on context threshold (>80% budget) for seamless recovery.
Checkpoint Template
# Session Checkpoint
Date: {{TIMESTAMP}}
Phase: {{CURRENT_PHASE}} | Task: {{TASK_ID}} | Progress: {{PHASE_PROGRESS}}%
## State
- Working on: {{TASK_DESCRIPTION}}
- Modified: {{FILE_LIST}}
## Decisions / Next / Resume Command
Recovery cost: AGENTS.md (300) + checkpoint (1.6K) = ~2K for instant recovery.
AGENTS.md Lean Template
Location: .codex/templates/AGENTS.lean.md
| Variable |
Source |
Example |
{{PROJECT_NAME}} |
DISCOVERY.md |
"Resumely" |
{{TECH_STACK}} |
DISCOVERY.md |
"Next.js+Supabase" |
{{CURRENT_PHASE}} |
PROGRESS.md |
"2" |
{{PHASE_PROGRESS}} |
TASKS.md calc |
"60" |
| Format |
Tokens |
Savings |
| Standard AGENTS.md |
~1,700+ |
baseline |
| Lean AGENTS.md |
~300 |
~82% |
Agent MANIFEST Pattern
Location: .codex/agents/MANIFEST.md
1. MANIFEST.md loaded (~500 tokens, 25 agents × 1 row)
2. Match user intent → keyword lookup
3. Load only matched agent file (~1-3K tokens)
Total: ~1.5-3.5K per invocation vs. ~38K if all loaded
Best Practices
| # |
Practice |
| 1 |
Start Lean: Ultra-lean AGENTS.md + MANIFEST only |
| 2 |
Task-First: Scope to current Task, not entire Phase |
| 3 |
Expand Incrementally: Add files only when referenced |
| 4 |
Structured > Prose: Use tables/key-value over paragraphs |
| 5 |
Checkpoint Often: Auto-save before context exhaustion |
| 6 |
Phase-Scoped Loading: Load current Phase docs by default |
| 7 |
Summarize Adjacents: Only SPEC.md from neighboring Phases |
| 8 |
Budget Awareness: Match loading strategy to session type |
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
tomevault-io