context-compact

Context Compact

Reduces active context size during long agent sessions without losing progress. Core principle: checkpoint first, then prune — never discard work that has not been written to disk.

When to Use

Invoke when any of the following is true:

• budget-monitor emits P3 INFO at 80% token budget
• Context window fill reaches 90% (Claude Code compact warning)
• Session spans more than ~20 file reads or tool invocations
• Sprint run covers 8+ tickets
• Security triage ingests findings from 2+ scanners simultaneously
• A single tool output exceeds ~500 lines

Compaction Strategies

1. Checkpoint to Disk (Always First)

Before pruning anything from active context, write current work state to disk:

Agent family	Checkpoint file
Sprint	sprint-plan.json (partial — save completed tickets)
Security	.security-triage-state.json (findings processed so far)
Backend / Frontend / DB / DevOps	.agent-checkpoint.json (completed + pending subtasks)
Guardrails	.guardrails-audit.jsonl (streaming — no extra step needed)

Minimal checkpoint format:

{
  "sessionId": "backend-coding-agent-20260317T102300Z",
  "completedTasks": ["task-a", "task-b"],
  "pendingTasks": ["task-c"],
  "lastProcessedItem": "PROJ-142",
  "summaryNotes": "Auth service refactored; tests passing. Next: API gateway."
}

2. Delegate Large Tasks to Subagents

Use the Agent tool for any task that would require reading many files or producing large outputs. Subagents run in isolated context — their result returns as a compact summary.

When to delegate:

• Analysing a file >200 lines → delegate with a targeted question
• Searching a pattern across 10+ files → delegate
• Running a full code review on a module → delegate

The result arrives in ~50 tokens instead of burning 2,000+ tokens of raw file content.

3. Read Selectively

Instead of	Use
Read entire file (800 lines)	Read file offset=N limit=50
Read config to find one key	Grep pattern="key:" file=config.json
Read all test files	Glob *.test.ts then read only the failing ones

4. Summarise Before Moving On

When a large tool output has been processed, replace it in working memory with a 1–3 line summary before moving to the next task. Do not refer back to the raw output.

Example — after reading 300 lines of a Go file:

"Reviewed auth/service.go: RS256 JWT validation, no refresh-token logic, 3 methods need unit tests."

5. Rotate Logical Units Within the Session

When moving between major work units (e.g., ticket-to-ticket in a sprint run, scanner-to-scanner in a security triage):

1. Write the completed unit's output to disk.
2. Clear internal notes about that unit.
3. Load only what the next unit requires.

This is not a new Claude Code session — it is a deliberate context boundary within the same session.

Integration with Budget Monitor and Context Window

80% token budget (P3 INFO from budget-monitor)

1. Run Strategy 1 (checkpoint to disk) immediately.
2. Switch to Strategy 2 (subagent delegation) for all remaining reads.
3. Do not start a new major work unit — finish the current one cleanly and stop.

90% context window fill (Claude Code compact warning)

This fires based on the raw context window fill, independent of the token budget config. It is a harder signal — act immediately:

1. Run Strategy 1 (checkpoint to disk) if not already done.
2. Stop all new file reads and tool calls that are not strictly required to finish the current subtask.
3. Produce the final output for the current subtask now, even if incomplete, with a clear PARTIAL: prefix and pointer to the checkpoint file.
4. Do not attempt to start the next subtask in this session — let the next session resume from the checkpoint.

At 100% of maxTokensPerSession, budget-monitor blocks. If context-compact was applied at 80%/90%, all progress is already on disk and the next session can resume from the checkpoint.

Quick Reference

Signal	Action
P3 INFO from budget-monitor (80% token budget)	Checkpoint → switch to subagent delegation
Context window 90% fill (compact warning)	Checkpoint → stop new reads → emit PARTIAL: output now
File >200 lines needed	Subagent or selective read with offset/limit
Sprint run with 8+ tickets	Process in 4-ticket batches; checkpoint after each batch
Multi-scanner triage	One scanner per logical unit; checkpoint between scanners
Tool output >500 lines	Summarise inline; discard raw output from active context
Moving to next major task	Write unit output to disk before loading next unit