Context Management

Manage your context window, survive compaction, persist state across turns.

<when_to_use>

Planning long-running or multi-step tasks
Coordinating multiple subagents
Approaching context limits (degraded responses, repetition)
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.

What Goes in Tasks

Category	Example
Current work	`Implementing auth refresh flow` (status: in_progress)
Completed work	`JWT validation logic added to middleware` (status: completed)
Discovered work	`Handle token expiry edge case` (status: pending)
Key decisions	Embed in task description: "Using RS256 per security review"
Agent handoffs	`[reviewer] Review auth implementation` + metadata: `{agentId: "abc123"}`
Blockers	Create blocker task, use `blockedBy` field

Task Discipline

Exactly one in_progress at any time. Call TaskUpdate to mark in_progress before starting.

Mark complete immediately. Don't batch completions — TaskUpdate with completed as you finish.

Include agent IDs for resumable sessions in task metadata.

Expand dynamically. TaskCreate as you discover work; don't front-load everything.

Action-oriented subjects. Use verbs: "Implement X", "Fix Y", "Review Z"

Status Flow

pending → in_progress → completed
                ↓
         (blocked → TaskCreate for blocker, add blockedBy)

If blocked, don't mark complete. Create a new task for the blocker and link with addBlockedBy.

Pre-Compaction Pattern

As context fills, ensure tasks capture progress. Use TaskUpdate to add details to in_progress task description:

Task: Implementing token refresh
Description:
  - Refresh endpoint: POST /api/auth/refresh
  - Token rotation: enabled
  - Refresh window: 5 minutes before expiry
  - Remaining: validation logic

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.

Default Stance

If a task can be delegated, delegate it.

Delegation Decision Tree

Task arrives
├── Exploration/research? → Explore agent (always)
├── Multi-file reading? → Subagent (summarizes for you)
├── Independent subtask? → Background agent
├── Specialized expertise? → Domain agent (reviewer, tester, etc.)
└── Simple, focused, single-file? → Main agent (maybe)

Note: Plugin agents require the plugin:agent-name format (e.g., outfitter:reviewer). Built-in agents (Explore, Plan, general-purpose) work without prefix. Use /agents to see available agents.

Context-Saving Patterns

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": "outfitter:reviewer", "run_in_background": true, "prompt": "Security review..." }
{ "subagent_type": "outfitter:analyst", "run_in_background": true, "prompt": "Performance review..." }

Main agent: stays lean, collects results when ready.

Background execution — For independent work:

{
  "subagent_type": "outfitter:tester",
  "run_in_background": true,
  "prompt": "Run integration tests for auth module"
}

Continue other work; retrieve with TaskOutput later.

Task Integration

Track delegated work in tasks:

[analyst] Research caching strategies (pending, metadata: {taskId: "def456"})
[engineer] Implement cache layer (pending, blockedBy: analyst task)
[reviewer] Review cache implementation (pending, blockedBy: engineer task)
[tester] Validate cache behavior (pending, blockedBy: reviewer task)

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.

Saving State

At session end or before long pause:

{
  "tool": "episodic-memory:save",
  "content": {
    "task": "Implementing auth refresh flow",
    "status": "in_progress",
    "completed": ["JWT validation", "Refresh endpoint structure"],
    "remaining": ["Token rotation logic", "Tests", "Security review"],
    "decisions": {
      "library": "jose",
      "algorithm": "RS256",
      "refresh_window": "5 minutes"
    },
    "files_modified": ["src/auth/refresh.ts", "src/auth/middleware.ts"],
    "next_steps": "Implement token rotation in refresh.ts:42"
  }
}

Restoring State

At session start:

{
  "tool": "episodic-memory:search",
  "query": "auth refresh implementation"
}

Then reconstruct tasks from saved state using TaskCreate.

When to Use Cross-Session

Multi-day projects
Complex refactors with many steps
Work that will be interrupted
Handing off to future sessions

For single-session work, Tasks alone suffice.

</cross_session>

Workflow Integration

At Task Start

TaskCreate with initial scope
If complex: use Plan subagent to explore, preserve main context
TaskUpdate first task to in_progress

During Execution

TaskUpdate as work progresses
Delegate exploration to subagents
Mark completed immediately (no batching)
TaskCreate for discovered work
Note decisions in completed task descriptions

Approaching Compaction

Run pre-compaction checklist
Ensure current state captured in in_progress task description
Record any background agent IDs in task metadata

After Compaction

TaskList to read task state (it persists)
Resume from in_progress task
Use saved details to continue without re-exploration

At Task Completion

TaskUpdate final tasks to complete with outcomes in description
If multi-session: save to episodic memory
Report summary to user

ALWAYS:

Use Tasks for any work over 2-3 steps
TaskUpdate before significant actions
Mark completed immediately, not batched
Include agent IDs in task metadata for resumable sessions
Delegate exploration to subagents (preserves main context)
Record decisions in completed task descriptions
Run pre-compaction checklist when context fills

NEVER:

Rely on conversation history surviving compaction
Keep large research results in main context (delegate or summarize)
Have multiple in_progress tasks simultaneously
Stop early due to context concerns (persist state instead)
Batch multiple completions together
Leave tasks vague ("do the thing" → "Implement refresh endpoint")

task-patterns.md — deep patterns and templates
delegation-patterns.md — context-preserving delegation
cross-session.md — episodic memory integration
subagents skill — agent orchestration patterns

context-management