Compact a long conversation with /compact

/context has told you what’s wrong: the conversation is half the window and climbing, and the agent is getting hazy under the weight of four days of history. But you’re in the worst possible spot for the two fixes you already know. You can’t /clear — that drops the very thread you’re still working in, and Thursday’s task isn’t finished. And resuming a leaner session wouldn’t help; the bloat is this session. You’re not done, you’re not leaving, you’re just out of room.

This is the situation compaction exists for: keeping the understanding while spending far fewer tokens to carry it.

Condensing the thread

/compact                                          # summarise the thread, keep the essentials
/compact keep the rate-limiter design and which tests still fail   # steer what survives

Compaction replaces the long back-and-forth with a summary of itself. The load-bearing parts — the goal, the decisions you reached, the current state of the code, the most recent turns — stay. The verbose middle — full file contents the agent read on Tuesday, exact command output, the validation approaches you explored and discarded — collapses to a few lines of prose. You come out with the same working understanding in a fraction of the footprint:

> /compact keep the rate-limiter design, the per-route auth decision, and the failing tests

  ⎿ Compacted. Conversation 96k → 11k tokens.
     Kept: goal, in-memory-LRU limiter, per-route role checks, hand-rolled
           validation, 2 failing tests + their output. Summarised: 4 days of turns.

> /context
  Conversation   11k    6%          ← room to breathe again

> now fix the second failing test
  [carries on with the whole week's context intact, 85k tokens lighter]

That instruction on the second form matters more than it looks. Left to its own judgment, compaction guesses at what’s important; told what you can’t lose, it keeps the rate-limiter design in full detail instead of compressing it away to make room for something you stopped caring about on Tuesday. When the thread has a clear protagonist, name it.

Claude Code will also compact on its own as you approach the limit — so even if you never learn the command, a long session degrades gracefully instead of hitting a wall. Running /compact yourself isn’t about whether it happens; it’s about timing. You choosing the moment — at a clean boundary, with an instruction — beats the tool choosing it for you in the middle of a delicate step.

The trap that actually bites people

Here is the one thing to take from this lesson if you take nothing else: compaction is lossy, so write unsaved work to disk first. If a change exists only in the conversation — the agent described a diff in detail but you never actually wrote it to a file — compaction can flatten “here’s the exact new implementation of validate()” down to “edited the validation,” and the specifics are simply gone. They were never anywhere but the chat, and the chat just got summarised. Save, then compact: get the work into a file, a commit, or a plan before you condense the thread that’s holding it. Make this reflexive and compaction is free; skip it once on the wrong turn and you’ll learn it the expensive way.

That’s also the case against leaning on automatic compaction through a delicate stretch. If you’re mid-refactor with uncommitted state and intricate reasoning in flight, an auto-compaction at the wrong instant can summarise away a nuance you needed. When you’re in that kind of moment, get to a committable state and compact deliberately — don’t let it surprise you with scissors.

And the old decision returns one more time, from the compaction side: compact keeps the thread, clear drops it. Still on this task, low on room — compact. Done with it, moving to something unrelated — clear. Compacting when you should have cleared just preserves noise more efficiently; clearing when you should have compacted throws away the week.

Closing the loop

For the rare reset that even compaction can’t give you — you want a genuinely empty window but still need to carry the plan forward — there’s one more move, and it’s really this whole chapter’s lesson in miniature. Write the state down to disk: a plan file, a progress note, an update to CLAUDE.md. Then /clear to nothing, and have the next session read it back. Compaction keeps the thread alive in place; a disk handoff lets you start completely fresh without losing the plot. Same instinct either way — keep the decisions, drop the noise.

It’s Friday. The rate limiter is in, the auth checks are per-route, the validation is hand-rolled, the tests are green, and the session that carried all of it never once fell over — because every time it threatened to, you had the move. You resumed it across the weekend, cleared it for the interloping bug, rewound it off a bad path, branched it to choose a design, watched its window with /context, and compacted it to the finish.

That’s the whole skill. Not any single command — the running habit of treating the agent’s context as a resource you can see, spend, branch, reclaim, and hand off at will. Carry that into every other module in this course, because every primitive ahead of you spends the same window you just learned to manage.