11 KiB
description
| description |
|---|
| Smart context compact - preserve essential Navigator markers and documentation context |
Navigator Smart Compact
You are performing a context-optimized compact operation that preserves essential Navigator documentation markers.
What This Does
Regular /compact: Clears all conversation history, loses context
Navigator /nav:compact:
- Generates a context marker (snapshot of where you are)
- Saves marker to
.agent/.context-markers/ - Shows you exactly how to resume
- Clears conversation history
- You restore context in your next session by reading the marker
The Magic: Context markers compress your entire session (50+ messages, 130k tokens) into a focused summary (3k tokens) that captures only what matters: current task, decisions made, next steps.
How Context Markers Work
Think of it like save points in a video game:
Before Compact:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
You: "Help me implement auth"
Claude: [50 messages of implementation]
You: "Now add OAuth"
Claude: [20 messages of OAuth work]
Total: 130k tokens, approaching limit
After /nav:compact:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Marker saved: .agent/.context-markers/2025-10-12.md
Contains:
- Task: TASK-45 (auth + OAuth)
- Status: OAuth integrated, needs testing
- Decisions: Using passport.js, JWT tokens
- Next: Write tests for OAuth flow
- 3k tokens
Next session:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
You: Read @.agent/.context-markers/2025-10-12.md
Claude: *knows exactly where you left off*
You: "Write the OAuth tests"
Claude: *continues seamlessly*
You never lose progress. The knowledge is preserved, just compressed.
When to Use
✅ Good Times to Compact
After isolated sub-tasks:
- Just finished documentation update
- Created SOP for solved issue
- Archived feature implementation plan
- Completed debugging session
Before context switches:
- Switching from feature A to feature B
- Moving from debugging to new feature
- Starting new sprint/milestone
- After research phase, before implementation
Token optimization:
- Approaching 70% token usage
- Long conversation with repeated info
- After multiple /nav:update-doc operations
❌ Bad Times to Compact
In middle of work:
- Feature half-implemented
- Debugging complex issue
- Multiple related sub-tasks pending
Context still needed:
- Next sub-task depends on current conversation
- Need to reference recent decisions
- Team discussion ongoing
Compact Process
Step 1: Identify Essential Context
Scan conversation for:
Must preserve:
- Current task ID (TASK-XX)
- Active feature/epic name
- Key technical decisions made
- Unresolved blockers/questions
- Next steps planned
Can clear:
- Completed sub-tasks details
- Resolved debugging sessions
- Documentation already written
- Exploratory research (if documented)
Step 2: Generate Context Marker
Create compact marker to preserve essentials:
# Navigator Context Marker (Post-Compact)
**Session**: [Date/Time]
**Navigator**: .agent/DEVELOPMENT-README.md
## Active Work
- **Task**: TASK-XX - [Feature Name]
- **Status**: [Phase/Progress]
- **Location**: [File/component being worked on]
## Recent Decisions
- [Decision 1]
- [Decision 2]
## Documentation State
- **Task docs**: [List updated docs]
- **System docs**: [List updated docs]
- **SOPs**: [List created SOPs]
## Next Steps
1. [Next action]
2. [Following action]
## Blockers
- [Blocker 1 if any]
## Don't Load Again (Already Documented)
- [Doc 1] - Already in .agent/
- [Doc 2] - Already in .agent/
---
Load this context marker after compacting to resume efficiently.
Step 3: Save Context Marker
IMPORTANT: You MUST save the marker where the user can access it after compact.
Recommended: Save to .agent/.context-markers/ directory
# Create directory if doesn't exist
mkdir -p .agent/.context-markers
# Save with timestamp
Write(
file_path: ".agent/.context-markers/2025-10-12-143022-compact.md"
content: [context marker from Step 2]
)
Step 3.5: Mark as Active Marker
NEW: Create .active file to enable automatic resume
# Create .active file pointing to this marker
echo "2025-10-12-143022-compact.md" > .agent/.context-markers/.active
This enables: /nav:start will auto-detect and load this marker
Show user the saved location:
✅ Context marker saved and marked as active:
.agent/.context-markers/2025-10-12-143022-compact.md
This marker will be auto-loaded on next session start.
Alternative locations:
Option 2: Append to current task doc (if task exists)
Append to: .agent/tasks/TASK-XX-feature.md
## Session Notes
### Compact Point - [Date]
[Context marker content]
After compact: Read @.agent/tasks/TASK-XX-feature.md
Option 3: User clipboard (if no task doc yet)
⚠️ No task doc exists yet.
Copy this marker and paste it in your next session:
[Show marker content]
Or save it manually before compacting.
Step 4: Show Resume Instructions
CRITICAL: Tell the user exactly how to resume.
╔══════════════════════════════════════════════════════╗
║ ║
║ 🔄 Ready to Compact ║
║ ║
╚══════════════════════════════════════════════════════╝
✅ Context marker created and marked as active:
.agent/.context-markers/2025-10-12-143022-compact.md
TO RESUME AFTER COMPACT:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Simply run: /nav:start
This will automatically:
• Load navigator (.agent/DEVELOPMENT-README.md)
• Detect active marker
• Restore your context (~3k tokens)
• Load current task (if applicable)
All in one command. No manual steps needed.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Proceed with compact? Type 'yes' to continue.
Wait for confirmation before compacting.
Step 5: Perform Compact
Only after user confirms, execute Claude Code's /compact command.
Step 6: Post-Compact Resume (For User's Next Session)
Immediately after compact:
-
Load navigator (always):
Read .agent/DEVELOPMENT-README.md (~2k tokens) -
Load context marker:
Read context marker from Step 2 -
Load active task doc (if exists):
Read .agent/tasks/TASK-XX-feature.md (~3k tokens) -
Resume work: Continue where left off
Total tokens loaded: ~7k (vs 60k+ if keeping full conversation)
Compact Strategies
Aggressive (Compact Often)
When: Token-constrained, switching tasks frequently
Trigger:
- After every sub-task
- Before every new task
- Every 50% token usage
Trade-off: More compacts, less context continuity
Best for: Multiple short tasks, exploratory work
Conservative (Compact Rarely)
When: Deep work on single feature, need context continuity
Trigger:
- After major milestones only
- When reaching 70%+ tokens
- Between unrelated epics
Trade-off: Fewer compacts, more token usage
Best for: Complex features, long debugging sessions
Manual (User Decides)
When: User knows when to compact
Trigger: User runs /nav:compact explicitly
Trade-off: Full control, requires judgment
Best for: Experienced users, custom workflows
Configuration
Set in .agent/.nav-config.json:
{
"compact_strategy": "conservative",
"compact_trigger_percent": 70,
"save_context_markers": true,
"context_marker_location": ".agent/.context-markers/"
}
Example Compact Scenarios
Scenario 1: Feature Complete
Before Compact:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Tokens: 65% (130k used)
Conversation: 50+ messages
Feature TASK-123 complete
Docs updated
Tests passing
Action: /nav:compact
Reason: Feature done, docs archived, ready for next task
After Compact:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Tokens: 5% (10k used)
- Navigator loaded (2k)
- Context marker (3k)
- Ready for TASK-124
Savings: 120k tokens freed (60% of budget)
Scenario 2: Research → Implementation
Before Compact:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Tokens: 45% (90k used)
Research: Explored 5 different approaches
Decision: Chose approach #3
Key findings: Documented in SOP
Action: /nav:compact
Reason: Research done, documented, time to implement
After Compact:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Tokens: 7% (14k used)
- Navigator (2k)
- Task doc with decision (3k)
- Relevant SOP (2k)
- Implementation ready
Savings: 76k tokens freed
Scenario 3: Multi-Task Day
Morning:
- TASK-101: Bug fix (15k tokens)
- /nav:compact
- TASK-102: New feature (25k tokens)
- /nav:compact
Afternoon:
- TASK-103: Integration (20k tokens)
- /nav:compact
- TASK-104: Documentation (10k tokens)
Total work: 4 tasks
Peak usage: 25k tokens (12.5%)
Without compact: Would hit 70k+ (35%), slower responses
Benefit: Maintained fast responses all day
Compact Checklist
Before running /nav:compact:
- Current task completed or at good stopping point
- Important decisions documented (task doc or SOP)
- No unresolved blockers requiring conversation context
- Ready to switch tasks or take break
- Context marker generated (if needed)
After running /nav:compact:
- Load navigator (.agent/DEVELOPMENT-README.md)
- Load context marker (if saved)
- Load active task doc (if continuing work)
- Verify ready to continue
Advanced: Auto-Compact
Future enhancement: Automatically compact based on triggers
{
"auto_compact": {
"enabled": false,
"triggers": {
"token_percent": 70,
"after_update_doc": true,
"between_tasks": true
},
"require_confirmation": true
}
}
When trigger hit:
⚠️ Navigator Auto-Compact Suggested
Reason: Token usage at 71%
Action: Run /nav:compact to free 60k+ tokens
Compact now? [Y/n]:
Metrics
Track compact efficiency:
Before Compact:
- Tokens used: 130k (65%)
- Message count: 50+
- Time: 2 hours
After Compact:
- Tokens used: 10k (5%)
- Context preserved: Task doc + decision markers
- Ready for: Next task immediately
Savings:
- 120k tokens freed
- 60% of budget reclaimed
- Fast responses restored
Remember: Navigator compact preserves what matters (documented knowledge) and clears what doesn't (conversation history). This keeps your context lean and your sessions productive.