Claude Code /compact: What It Does, What Survives

There's a hidden mechanic in Claude Code that most people don't think about until it costs them an hour of work. Compaction is the automatic compression of your conversation context when you approach the token limit. I ran into it when my always-on agent "forgot" a critical rule from the beginning of a session after 200 minutes of continuous operation. Here's what I learned by digging into how it works.

What is compaction and why it exists

Claude Code runs in your terminal and maintains long sessions. Unlike ChatGPT where each message is a separate request, Claude Code accumulates context: files it read, commands it executed, grep results, diffs, error messages. All of this stacks into one massive prompt.

The problem: every model has a context limit. Claude Code can compact automatically as the conversation approaches its auto-compact window. The default depends on the model. On versions that support it, run /autocompact to inspect the window for the current model and /context to see what is taking up space. See the Claude Code command reference.

What happens: Claude Code takes the entire conversation history, sends it to a separate model call with a prompt like "compress this into key facts," and replaces the full history with a condensed summary. You don't see this happening — at some point, the agent starts working from "memory" of past interactions rather than the full transcript.

What survives /compact in Claude Code

Anthropic's newer docs are more explicit about the context window. Before you type anything, Claude Code loads startup context: system prompt, output style, project rules, CLAUDE.md, auto memory, MCP tool names, and skill descriptions. During a session, every file read, command result, diff, and tool output adds more context. When compaction happens, the conversation is replaced by a summary and startup context is reloaded.

What survives compaction, what doesn't

From my experience running agents daily, compaction reliably preserves:

• The current task and its immediate context
• File names that were recently modified
• Recent errors and their solutions
• General project architecture

What consistently gets lost:

• Instructions from the start of the session — "don't touch this file," "use this format"
• Intermediate decisions — why you chose approach A over B
• Specific code snippets discussed 50 messages ago
• Subtle style rules — "no emoji," "no Co-Authored-By in commits"

This makes sense: compaction optimizes for "what to do next," not "why we did what we did." Decision context is the first casualty of compression.

Custom compaction prompts

For one compaction, tell Claude Code what you need for the next step:

/compact Keep the current plan, changed files, failing tests, and the next command to run.

For recurring guidance, add a section like this to your project’s CLAUDE.md:

## Compact Instructions

Keep the active task, changed file paths, and the last test results.
Preserve user corrections and decisions that constrain the next step.
Summarize long tool output and keep the paths needed to check it.

Both are documented in Anthropic’s context guide. After compaction, ask Claude to read your checkpoint and name the next action before it starts editing again.

CLAUDE.md vs compaction: where to put what

The key insight from three months of running Claude Code agents: never rely on compaction for critical rules. Everything the agent must always remember should live in CLAUDE.md.

Claude Code re-reads the root CLAUDE.md after compaction. Rules tied to specific paths can load when Claude reads those files again. Keep project-wide guidance short and put decisions you need to verify in a project file.

My strategy:

• CLAUDE.md — architectural rules, code style, prohibitions, credential paths, naming conventions. Anything that applies to every session
• Conversation context — current task, intermediate results, discussions. It's OK to lose this during compaction
• Project files — TODO.md, ARCHITECTURE.md, notes. The agent can re-read these if compaction erased the context

Rule of thumb: if you catch yourself repeating the same instruction to the agent — move it to CLAUDE.md. I covered CLAUDE.md configuration in detail in my Claude Code setup guide.

How to tell when compaction happened

Claude Code shows a [context compacted] indicator in the terminal. But if you're multitasking, it's easy to miss. A more reliable signal: watch the cost counter in the bottom-right corner. A sudden cost spike (compaction is a separate API call) plus a context counter reset means compaction just fired.

Another telltale sign: the agent starts re-asking things you already discussed. "Which file has the config?" — even though you edited that file 20 minutes ago. That's a clear signal that context was compressed and details were lost.

When compaction causes real problems

A concrete case from my work. I run a server-agent — Claude Code running 24/7 on a VPS, accessible via Telegram. The agent receives a message, processes it, waits for the next one. Sessions can last hours.

The problem: after compaction, the agent would "forget" access control rules. I have a permission matrix — which files can be read from which chat context. These rules were in the initial prompt, but after compression the model lost them and started responding to requests it should have blocked.

I moved those rules into CLAUDE.local.md so they could be read from disk. For an access boundary that must hold even if Claude misses an instruction, enforce it in the tool or use Claude Code permission rules.

When to run /compact manually

Manual /compact is best at natural task boundaries: after a PR is merged, after a debugging path is understood, or before switching from research to implementation. If you wait for auto-compaction, it can happen mid-task, exactly when the model is juggling the most fragile context.

Use /rewind to return to an earlier checkpoint. The menu lets you restore the conversation, tracked file changes, or both. It also offers a summarize option. Check the diff before choosing a code restore.

Prompt caching cost of compaction

Claude Code uses prompt caching automatically. Compaction invalidates the conversation-history layer because the next request has a new shorter history. The system prompt layer can still be reused, but the next turn after compact may feel slower or more expensive. This is fine when you are keeping useful context; it is wasteful if you compact a messy failed branch that should have been rewound.

PreCompact and PostCompact hooks

Claude Code exposes hook events around compaction: PreCompact before the compact operation and PostCompact after it completes. This is underrated for long-running agents.

A practical hook can write a tiny checkpoint before compact:

• current task;
• files modified;
• commands/tests already run;
• critical user constraints;
• open questions.

After compact, ask Claude to read that checkpoint and verify it still remembers the constraints. This is much more reliable than hoping a generic summary preserved everything.

Auto-compaction thrashing

If Claude Code compacts and immediately fills the context window again, docs call this auto-compaction thrashing. The usual cause is a huge file or tool output being re-read. Recovery is boring but effective: read smaller line ranges, ask for summaries, move durable rules into CLAUDE.md, and compact with a focused instruction.

Practical tips for managing compaction

Give /compact a focus. Working with data? Ask it to keep the SQL file, the date range and the assumptions behind the query.

Keep sessions short when possible. A fresh session means clean context plus full CLAUDE.md. Sometimes that's better than a long session with two compaction events. I've found that breaking work into focused 30-60 minute sessions produces better results than marathon 4-hour runs.

Use files as external memory. Ask the agent to write key decisions to a TODO.md or NOTES.md file in your project. After compaction, it can re-read them. This pattern is especially important for Obsidian-based workflows where the vault acts as long-term memory.

Put everything critical in CLAUDE.md. Rules that must always apply go there, nowhere else. Don't hope that compaction will preserve them — assume it won't.

Test compaction intentionally. Run a long session, wait for compression, then check — does the agent still remember the rules from the beginning? This will save you hours of debugging later.

Compaction isn't a bug — it's a necessary compromise. Context windows are growing, but as long as they're finite, compression will be part of working with AI agents. Better to understand how it works than to be surprised when your agent "forgets" a critical rule at the 200-minute mark.

Follow me on Twitter/X @danokhlopkov for more on AI agents and automation.