Manage context window, survive compaction, persist state. Use when planning long tasks, coordinating agents, approaching context limits, or when context, compaction, tasks, or persist state are mentioned.
Manage context window, survive compaction, persist state. Use when planning long tasks, coordinating agents, approaching context limits, or when context, compaction, tasks, or persist state are mentioned.
Need to preserve state across compaction or sessions
Orchestrating complex workflows with handoffs
NOT for: simple single-turn tasks, quick Q&A, tasks completing in one response
</when_to_use>
Claude Code operates in a ~128K token context window that compacts automatically as it fills. When compaction happens:
What survives:
Task state (full task list persists)
Tool results (summarized)
User messages (recent ones)
System instructions
What disappears:
Your reasoning and analysis
Intermediate exploration results
File contents you read (unless in tool results)
Decisions you made but didn't record
The consequence: Without explicit state management, you "wake up" after compaction with amnesia — you know what to do, but not what you've done or decided.
Tasks: Your Survivable State
Tasks are not just a tracker — they're your persistent memory layer. Use TaskCreate, TaskUpdate, TaskList, and TaskGet to manage state that survives compaction.
Decisions embedded in completed task descriptions. Current state detailed in active task. Future work queued as pending.
<pre_compaction>
Pre-Compaction Checklist
Run through this when context is filling (you'll notice: slower responses, repetition, degraded reasoning):
Capture progress — What's done? TaskUpdate completed tasks with outcomes in description.
Record decisions — What did you decide? Why? Put in task descriptions.
Note current state — Where exactly are you in the current task? TaskUpdate the in_progress task with specifics.
Queue discovered work — What did you find that needs doing? TaskCreate as pending.
Mark dependencies — What needs what? Use addBlockedBy in TaskUpdate.
Include agent IDs — Any background agents? Record IDs in task metadata.
Example: Before Compaction
Bad (state will be lost):
- [x] Research auth approaches
- [ ] Implement auth
- [ ] Test auth
Good (state survives):
- [x] Research auth approaches → middleware + JWT (see src/auth/README.md)
- [ ] [in_progress] Implement JWT refresh flow
- Using jose library (already in deps)
- Endpoint: POST /api/auth/refresh
- Handler started in src/auth/refresh.ts:15
- Remaining: validation logic, token rotation
- [ ] Add refresh flow tests (after impl)
- [ ] [reviewer] Security review auth module (after tests)
</pre_compaction>
Delegation for Context Preservation
Main conversation context is precious. Every file you read, every search result, every intermediate thought consumes tokens. Subagents run in isolated contexts — only their final output returns.
Research delegation — Instead of reading 10 files:
{"description":"Find auth implementation","prompt":"Locate authentication-related files, summarize the auth flow","subagent_type":"Explore"}
Main agent receives: concise summary, not 10 file contents.
Parallel review — Instead of sequential analysis:
// Single message, multiple calls, all run_in_background: true{"subagent_type":"reviewer","run_in_background":true,"prompt":"Security review..."}{"subagent_type":"analyst","run_in_background":true,"prompt":"Performance review..."}
Main agent: stays lean, collects results when ready.
Background execution — For independent work:
{"subagent_type":"tester","run_in_background":true,"prompt":"Run integration tests for auth module"}
Continue other work; retrieve with TaskOutput later.
When background agents complete, TaskUpdate status and process results.
What NOT to Delegate
Direct user Q&A needing conversation history
Simple edits to files already in context
Final synthesis requiring your judgment
<cross_session>
Cross-Session Patterns
For work spanning multiple sessions, use episodic memory MCP server.
Prerequisites: Cross-session patterns require an episodic-memory MCP server to be configured. If unavailable, skip this section — Tasks handle single-session persistence.
