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):

• Research auth approaches
• Implement auth
• Test auth

Good (state survives):

• 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