What happens when Claude Code compresses its conversation context?

What the documented compaction process does

Claude Code's context window is the model's working view for the next turn. It contains conversation history, file contents that Claude has read, command and tool outputs, system instructions, CLAUDE.md, auto memory, and loaded skills. As that view approaches its limit, Claude Code first removes older tool output and then summarizes conversation history if it still needs space. Claude Code context window

Manual /compact [instructions] replaces history with a summary and accepts an optional focus. For example, after finishing a database migration, /compact preserve the migration decision, changed files, test command, and outstanding rollback risk gives the summarizer a concrete preservation goal. /context shows what is consuming the current window, so it is the useful first command when a session feels bloated or is approaching a limit. Claude Code sessions

Anthropic documents one implementation detail that is useful for builders: Claude Code makes a separate summarization request with the same system prompt, tools, and prior history, plus a summarization instruction. The resulting summary replaces the conversation layer. The system prompt is reused, and project context is loaded again from disk. Claude Code prompt caching

The documentation does not specify a lossless compression algorithm, a fixed summary length, a ranking formula for every fact, or a guarantee that a particular early message survives. It describes the intended result, not a formal fidelity promise. A builder should therefore assume that compaction is useful working-memory management and that it can omit details that later prove important.

What remains available and what can disappear from working context

Compaction changes the conversation that Claude sees on subsequent turns. It does not modify the repository. The checkpoint documentation states that summarizing conversation does not change files on disk, and checkpoints can separately restore tracked Claude edits and conversation state. Claude Code checkpointing

That leads to a practical distinction:

CLAUDE.md is the right home for compact, stable project rules such as test commands, code conventions, prohibited actions, or how to handle generated files. Claude Code's documentation says project-root and user-level CLAUDE.md files are read at session start; a mid-session edit takes effect after the next /compact, /clear, or restart. Claude Code prompt caching Keep this file concise. Loading a very large instruction file also consumes context and can make the problem worse.

The transcript is not the same thing as the model's active context. Claude Code stores sessions locally as JSONL files by default, and /export can create a readable transcript. The session documentation warns that the JSONL format is internal and can change, so integrations should use the documented export or session interfaces instead of building a durable workflow around a private file format. Claude Code sessions Treat transcripts as potentially sensitive project data, because they may contain prompts, tool outputs, and command results.

A worked handoff for a long coding task

Consider a hypothetical session that is replacing an authentication middleware. Claude has read several source files, tried two approaches, changed src/auth.ts, and run a failing integration test. The early conversation contains the decision to preserve a legacy header until a client migration completes. If auto-compaction occurs later, the summary may retain the broad task and changed file, while losing the exact header name, failure output, or rejected approach.

Before compacting, put the durable facts in an external handoff note that a person can review. For example, docs/agent-handoff.md could contain:

Objective: move request authentication to the new middleware.
Constraint: accept X-Legacy-Auth until the client migration is complete.
Changed: src/auth.ts, tests/auth.integration.ts.
Status: unit tests pass; integration test "expired token" still fails.
Next: inspect token-clock fixture, then rerun pnpm test auth:integration.
Do not: deploy or remove the legacy header without release approval.

Then use /compact with a matching focus, or start a fresh task after the note and changes are saved. On the next turn, ask Claude Code to read the handoff note, inspect git diff, and run the named test before changing more code. The note creates a source of truth outside a lossy summary, and the test result confirms whether the resumed understanding matches the repository.

This is not a requirement to create a handoff file for every short task. It is worthwhile when work will span a long session, multiple people, a restart, a model change, or a consequential decision that would be costly to rediscover.

Choose compact, clear, rewind, or resume for the situation

/rewind is preferable when the problem is a specific detour rather than overall context size. Its menu can restore code, restore conversation, or summarize before or after a chosen message. The summarized options leave files on disk unchanged. Claude Code checkpointing /clear is better when the next task truly has different goals, because it removes unrelated material from the active window instead of asking a summary to carry it forward.

For a CLI session, /resume can reopen a saved conversation. Claude Code stores session transcripts continuously and supports claude --continue, claude --resume, and the in-session picker. Claude Code sessions Resuming restores continuity, but it should not replace a fresh check of the current branch, working tree, dependency state, and test results. Those can change while the session is inactive.

Builder controls for long-running or automated work

If you use the Claude Agent SDK, observe compaction rather than guessing that it happened. The SDK emits a system message with subtype compact_boundary when automatic compaction occurs. It also documents a PreCompact hook that can run custom logic, such as archiving a full transcript, before a manual or automatic compaction. Claude Code Agent SDK agent loop

Use that hook or your own task boundary to persist a small structured record outside the conversation: task ID, objective, acceptance criteria, changed-file list, current revision, test command and result, known risks, and next step. Do not archive secrets or raw user data by default. Your resume code can load that record, validate that the revision still exists, and ask the agent to re-read only the files relevant to the next action.

The same SDK documentation says a CLAUDE.md section can guide what the compactor should preserve, and that the heading is not magic. A plain instruction such as “When summarizing, preserve acceptance criteria, changed file paths, test results, and unresolved errors” is sufficient. Claude Code Agent SDK agent loop This improves the summary, but it does not replace an external handoff for a decision that must be exact or auditable.

Large tool outputs can trigger repeated compaction pressure. Claude Code documents that it stops auto-compacting after a few attempts if one large file or output immediately refills the context, rather than looping indefinitely. Claude Code context window In that case, inspect /context, reduce verbose command output, split the task, or clear the session after writing a handoff. Do not expect repeated summaries to make an oversized input reliably usable.