How Claude Code's automatic context compaction works, when it triggers, what it keeps, and how to control it. Covers the /compact command, compact hooks, and strategies for very long sessions.
Long Claude Code sessions accumulate hundreds of tool calls and file reads. Context compaction keeps them alive past the model's context limit — automatically, without losing the thread of what you're building.
How compaction works
Claude Code monitors token usage throughout the session.
At ~95% of the context window, it pauses the current turn.
It runs a summarization pass over the full conversation history.
The summary replaces the earlier turns in the context.
The session continues from the summary — same task, same file states, much smaller token count.
You'll see a notice in the chat: [Context compacted. Continuing from summary...]. The session continues normally.
Manual compact: /compact
# Trigger compaction before starting a new phase of work:
/compact
# With a hint about what to preserve:
/compact Focus on the authentication refactor decisions — discard the earlier
database schema discussion, that's already merged
Manual compaction is useful at natural breakpoints: after finishing one feature before starting the next, before a long context-heavy operation (reading a large codebase), or before handing off a session to a teammate.
Context usage at different file sizes
Activity
Approx. tokens per action
Actions before 190K limit
Reading a 100-line file
~300
~630 reads
Reading a 1,000-line file
~2,800
~68 reads
Edit + response cycle
~500–2,000
~95–380 cycles
Running tests (short output)
~200
~950 runs
Running tests (verbose, 500 lines)
~4,000
~47 runs
What to put in CLAUDE.md to survive compaction
Any invariant you'd be upset to lose after a compact should live in CLAUDE.md — Claude Code reads this file at the start of every session and after every compact.
# CLAUDE.md — project invariants
## API contracts (do not change these signatures)
- POST /api/v2/orders must remain backward-compatible with v1 clients
- The user_id field is always a UUID string, never an integer
## Performance budgets
- Homepage LCP < 2.5s on 4G (Lighthouse CI enforces this)
## Security constraints
- Never log PII fields: email, phone, address, payment_method
- All SQL goes through the ORM — no raw query strings
## Architecture decisions
- We chose server-side rendering over SPA for SEO reasons — do not
introduce client-side routing
Use CLAUDE.md aggressively — facts in CLAUDE.md survive compaction; facts in chat history don't.
Compact between phases — run /compact at natural breaks rather than hitting the automatic limit mid-task.
Limit verbose tool output — pipe long command output through head or tail in hooks to reduce token burn.
Split into sessions — for week-long projects, use git commits as session boundaries. Each new claude session starts clean; CLAUDE.md carries the context.
Worktrees for parallel work — see Claude Code worktrees to run parallel sessions without context interference.
Checking current context usage
# In any Claude Code session, ask:
"How much of your context window is used?"
# Or check via the status line if configured:
# The /status command shows token count and percentage used
Context compaction is an automatic process that triggers when a conversation is approaching the model's context window limit. Claude Code summarizes earlier turns into a compact transcript — preserving key decisions, file states, and task context — then continues the session from the summary rather than cutting off.
When does auto-compact trigger?
By default, compaction triggers when the conversation reaches approximately 95% of the model's context window. For Claude Sonnet (200K tokens), that's around 190K tokens — roughly 10-15 hours of intensive coding work, depending on file sizes read.
How do I manually trigger compaction?
Run /compact in the Claude Code chat. This immediately summarizes and compresses the conversation without waiting for the automatic threshold. Useful before starting a new major phase of work.
What does compaction keep vs. discard?
Compaction keeps: current file states, task objectives, key decisions made, constraints established, recent tool call results. It discards: intermediate reasoning, rejected approaches, verbose output from earlier commands, repeated file reads. The summary is purpose-built for continuing the task.
Does compaction lose context that matters?
Rarely, but it can. If you made a decision 100 turns ago that's relevant now, and it wasn't in the summary, Claude won't recall it. For critical invariants (security constraints, API contracts, performance budgets), add them to CLAUDE.md so they're always in context regardless of compaction.