Use Claude Code /compact command effectively
When and how to use Claude Code's /compact — what it actually does, the signals that say it's time, and the prompt patterns that produce a clean handoff.
On this page
A long Claude Code session accumulates two kinds of weight: the work you care about (decisions, files in flight, the plan) and the work you don’t (cat outputs, dead-end greps, rejected approaches, stale tool errors). /compact is how you keep the first and drop the second without losing your place.
The instinct is to treat /compact as a panic button when context fills up. That’s the worst time to use it — by then the model is already degraded and the summary it produces is shaped by the degradation. Used proactively, it’s closer to a checkpoint than a cleanup.
Context compaction
Replacing the running conversation with a model-written summary of what matters, then continuing from there.
/compact asks the model to summarise everything so far — the task, decisions made, files touched, open questions — and starts a fresh conversation seeded with only that summary. The new conversation costs less per turn, runs faster, and is no longer carrying the irrelevant log lines, dead branches, and verbose tool output that filled the original. The cost is whatever the summary missed.
When to compact
The signal isn’t “the context bar is full”. It’s earlier than that, and the symptoms are behavioural rather than visual.
-
The model starts repeating itself
Same file read twice in five turns. Same suggestion proposed and rejected, then proposed again. This means working memory is so full the model can’t keep its own recent reasoning straight. Compact now.
-
You're about to start a clearly separable phase
Finished investigation, about to implement. Finished implementation, about to write tests. Phase transitions are natural compaction points because the what mattered of the old phase fits in a paragraph, and the new phase doesn’t need the old phase’s tool output.
-
Tool output is dominating the context
A grep returned 400 lines. A test run dumped a stack trace. You don’t need the raw output anymore — you need the conclusion drawn from it. Compact and the summary will preserve the conclusion without the bulk.
-
You've changed direction
The first approach didn’t work; you’re now trying a different one. The failed approach’s edits, reads, and reasoning are dead weight. Compaction lets you carry forward the note (“approach A failed because X”) without the artefacts.
-
Before a hard task that needs full reasoning headroom
A subtle bug or a tricky refactor benefits from the model having room to think. Compact beforehand if context is already half-full, even if everything feels fine.
What is not a good signal: “the session is long.” A 200-turn session that stayed focused doesn’t need compaction. A 20-turn session that thrashed across three failed approaches does.
How to compact effectively
Default /compact produces a generic summary. That’s usually fine, but for anything load-bearing you should steer it with a prompt argument. The argument is treated as instructions for the summary, not as a continuation of the conversation.
/compactProduces a generic summary covering everything roughly equally. Fine for casual sessions. The summary will likely include things you don’t need (early exploration, rejected ideas) and may compress things you do need (the current plan, the file you’re mid-edit on).
/compact Preserve: the current refactor plan
for OrderService, the three files already
edited, and the failing test in
OrderServiceTest. Drop: the earlier
investigation into the unrelated logging
bug.Tells the summariser what’s load-bearing. The resulting context is leaner and the next turn starts with the right things in working memory.
A useful prompt template, when you have time to write one:
/compact Preserve: <the current task in one sentence>,
<the plan or decision we landed on>,
<the files/symbols/tests in flight>.
Drop: <the exploration / failed attempts / unrelated tangents>.
Open questions: <anything you want carried forward as a TODO>.The Open questions line is the underused one. It promotes loose threads in the conversation to first-class items in the new context so they don’t get summarised away.
The footguns
/compact invoked reactively, after the model has already started forgetting things or repeating itself.
The visible signal (context-bar percentage) lags the behavioural signal (degraded responses) by many turns. The bar is also the only on-screen indicator, so it feels authoritative.
Compact at phase transitions and direction changes, not at percentage thresholds. By the time the bar is red, the summary you get is shaped by an already-degraded model.
/compact with no argument, mid-implementation, then continuing as if the new context is equivalent to the old.
The default summary feels like a faithful condensation. It isn’t always — it’s a model judgement about what mattered, and it can quietly drop the specific decision or constraint that’s load-bearing for what comes next.
For load-bearing sessions, pass an explicit preserve/drop instruction. Read the summary the first turn after compaction — if a key constraint is missing, restate it before continuing.
Other traps worth naming:
- Compacting too often. Each compaction is lossy. Once per phase transition is healthy; every five turns is over-fitting to the context-bar and discards reasoning you’d benefit from re-reading.
- Compacting in the middle of an edit. The model is mid-thought on a specific change. The summary will record “in progress” but not the half-formed reasoning. Finish the unit of work first.
- Forgetting that compaction restarts grounding. Files the model was treating as “already read” need to be re-read after compaction. Earlier tool output, the model’s working theories of the codebase, and any partial reasoning that didn’t make it into the summary are all gone. MCP connections themselves persist — what’s lost is the conversation history containing their previous outputs.
Compact vs. subagent vs. clear
Three tools for context management, three different uses. They compose; they don’t replace each other.
| Axis | /compact | Subagent |
|---|---|---|
| What it does | Summarises the current conversation and continues from the summary | Spawns a child agent with its own context; only the result returns to the parent |
| When to use | You want to keep going on the same task with less weight | You want to delegate a self-contained query whose tool output is irrelevant to the main thread |
| What it costs | Whatever the summary misses; one extra turn of latency | Coordination overhead; the subagent has no shared memory with you |
| Reversibility | Lossy and forward-only | Fully reversible — the parent context is untouched |
/clear is the third option — wipe and start over. Use it when the current session is a write-off and a summary wouldn’t help (wrong task, deep down the wrong path). It’s the nuclear option; /compact is the scalpel.
The default order to reach for them: subagent first for the things that don’t belong in your context, /compact for natural checkpoints, /clear when the session itself is the problem. See 0002 Use subagents to protect the main context · Claude Code for the subagent half of the story.