Auto-triggers when context is getting large or when running long sessions. Provides smart context management: when to write handoff files, how to structure state for session chaining, how to spawn fresh sessions. Activates on: long session, context pressure, session handoff, memory management, running out of context.
Auto-triggers when context is getting large or when running long sessions. Provides smart context management: when to write handoff files, how to structure state for session chaining, how to spawn fresh sessions. Activates on: long session, context pressure, session handoff, memory management, running out of context.
version
1.0.0
Context Management for Long-Running Sessions
The Core Problem
LLMs degrade gradually starting around 30K tokens. Information in the middle of context is recalled 10-40% worse than at the edges. After ~100K tokens, you're operating at reduced capacity.
Prevention: Keep Context Lean
File Reading
Read only files you're about to edit
Use Grep to find specific patterns instead of reading whole files
Spawn subagents for exploratory reading — their context is separate
Subagent Isolation
Each subagent gets its own fresh context window
Send them specific instructions, get back structured results
The main agent's context only grows by the summary, not the raw exploration
Progressive Disclosure
Start with file names (Glob)
Then search for patterns (Grep)
Then read specific lines (Read with offset/limit)
Only read the full file when you're ready to edit it
Detection: Know When Context Is Full
Warning signs that you're approaching limits:
You've been working for 20+ tool calls without spawning subagents
You've read more than 10 files in the current session
You're re-reading files you read earlier (sign of context loss)
Your responses are getting less specific or accurate
Recovery: The Handoff Protocol
When you detect context pressure, write a handoff file:
.autopilot/handoff.md Structure
# Handoff — [Timestamp]## Current Task
[What I was working on]
## What's Done- [Completed item 1]
- [Completed item 2]
## What's Left- [Remaining item 1 with specific file:line references]
## Key Context- [Critical fact 1 that the next session MUST know]
- [Critical fact 2]
## Failed Approaches- Tried [X], failed because [Y] — DO NOT retry
## Files Modified This Session-`path/to/file.ts` — [what changed]
## Environment State- Branch: [current branch]
- Tests: [passing/failing]
- Uncommitted changes: [yes/no, what]
What Makes a Good Handoff
Concrete, not narrative: File paths and line numbers, not stories
Failed approaches: The most valuable section — prevents re-doing dead ends
Actual code snippets: For complex logic, include the key 5-10 lines
Decision rationale: Not just "chose X" but "chose X because Y"
Verification state: What tests pass, what's broken
What to Omit
General knowledge about the codebase (it's in CLAUDE.md)
Full file contents (they're on disk)
Explanations of how tools work
Narrative of the session ("First I tried...")
The Manus Pattern: Todo Recitation
For very long sessions, periodically rewrite your current task state to keep it fresh at the context boundary:
Every 10 tool calls, mentally review: "What am I doing? What's left?"
Write current state to handoff.md even if you're not switching sessions
