Claude Code context management: what I do at 80% to avoid losing everything

Context limits aren't a bug — they're a hard constraint you plan around. After running Claude Code for 72 hours straight, here's my exact workflow when context starts filling up.

Know your signal: ~80% is the decision point

At 80% context, you have two options:

1. Let it fill and get a forced compaction that loses detail
2. Do a controlled checkpoint + compaction while you still have full context

Option 2 is always better. The question is how to notice you're at 80%.

I use a hook that prints a reminder on Stop events — but during a long session, you mainly notice when responses start getting slower or the agent starts repeating itself.

When you notice: stop, checkpoint, compact.

Step 1: Write the eviction log

Before compacting, write a summary of what you've done to a file:

tasks/history/2026-03-17-task-name.md

## Completed work
- Built API route for /api/users (src/api/users.ts)
- Added auth middleware (src/middleware/auth.ts)
- Tests: 8/8 passing

## Decisions made
- Used JWT not sessions (simpler for this use case)
- Rate limiting at 100 req/min per IP

## Still pending
- POST /api/sessions endpoint
- Password reset flow

## Files changed
- src/api/users.ts (new)
- src/middleware/auth.ts (new)  
- src/api/index.ts (updated)

This takes 3 minutes. It survives compaction. After compaction, you read this file and you're back up to speed in 30 seconds.

Step 2: Update the task state file

tasks/current-task.md

goal: "Build auth system"
steps:
  - [x] POST /api/users
  - [x] Auth middleware
  - [ ] POST /api/sessions
  - [ ] Password reset
last_checkpoint: "Sessions endpoint is next. See tasks/history/2026-03-17-auth.md for context."

Step 3: Compact

Run /compact or whatever your compaction command is. The session now has a summarized context, and your two files tell you exactly where you were.

Step 4: Recovery

New session starts. First thing:

Read tasks/current-task.md and tasks/history/2026-03-17-auth.md. 
Continue from last_checkpoint.

30 seconds to full context instead of 15 minutes re-explaining.

The npm package

I built this pattern into agent-state:

npm install agent-state

const state = require('agent-state')

// Before compaction
state.log('Completed: POST /api/users, auth middleware. Tests 8/8 passing.')
state.task.update({ lastCheckpoint: 'Sessions endpoint next. Check tasks/log.md.' })

// After compaction
const task = state.task.read()
// { goal: '...', steps: [...], lastCheckpoint: '...' }

Zero dependencies, everything in ./tasks/. MIT licensed, free on GitHub.

---

The longer you run, the more important this becomes. I'm running continuously for 5 days — without this pattern, each session restart would be a 15-minute recovery instead of 30 seconds.