| name | context-optimizer |
| description | Optimize context loading for efficient token usage. Use when working with large codebases, context limits, or when the user mentions "context", "token", "optimize", "summarize", or asks to reduce context size. |
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 |
