Compact a long conversation with /compact

The task is unchanged: in the course’s running example, a small Express + TypeScript payments service with routes in src/index.ts and Vitest tests under tests/, the requirement is to add GET /healthz beside the existing GET /health. Both must answer HTTP 200 with the same JSON body, because existing callers poll the old address and a new monitor polls the new one; removing either breaks someone. The conversation that carried this task may now hold much more than that requirement: design discussion, an interruption, and rejected proposals. You need the decisions that came out of that work, but not necessarily every line that led to them.

The /compact command below is typed at the prompt of an active Claude Code conversation that already holds task history worth summarizing (the install lesson covers opening a session in a repo). If you do not have the payments project, use a task from your own repository instead: write down its one real requirement and the results you have actually seen before you continue.

Before compacting, make a short handoff in your notes or an agreed project file. Check it against the code and actual results. For this exercise it should answer:

• Which checkout and branch contain the work, and is it committed?
• Do both /health and /healthz currently exist?
• Which implementation was selected, or is the choice still open?
• Which tests ran, what did they report, and which checks remain unrun?
• What is the next action, and what remains outside scope?

If the earlier lessons were a walkthrough, record the answers as unknown rather than completing the story with imagined edits. A useful handoff can be short and still say that no implementation has been executed.

Tell the summary what matters

Run a focused compaction command in the continuing session:

/compact Preserve the requirement to keep both health addresses, the actual checkout and changed files, implementation decisions, tests that really ran, unresolved failures, and the next step. Keep proposals distinct from completed work.

The optional instructions steer the summary; they do not guarantee exact retention. The active context is the information the model can draw on for its next response, and it has a fixed capacity. Compaction replaces detailed history in that active context with a shorter account. Claude Code also manages context automatically as it fills, so save consequential decisions while working rather than assuming you can always wait until the last moment. See what compaction keeps.

You do not have to commit unfinished code to make a note durable. A file on disk can preserve a decision while the working tree remains uncommitted. Follow the project’s commit rules, and keep task-specific progress separate from standing project instructions. Today’s uncertain experiment should not quietly become tomorrow’s permanent rule.

Verify the handoff by using it

After compaction, ask for a reconstruction before another edit:

Restate the health-route contract and the next action from the summary.
Inspect the current files and compare them with the handoff.
Identify any missing decision or unverified result before continuing.
Do not edit yet.

If the answer omits /health, restore the preservation requirement from your notes. If it says the suite passed, compare that claim with the result you actually saved. Then use /context to inspect occupancy, meaning how much of the context’s capacity is in use. A smaller reading tells you that the active material shrank; it cannot tell you whether the summary kept the right facts.

A summary may leave out exact output or a proposed patch. That does not mean compaction deleted the working files or necessarily erased every saved transcript. Keep important artifacts directly accessible so recovery does not depend on searching an old conversation for the only copy of a decision.

If compaction repeatedly fails to create usable space, identify and narrow the oversized input before retrying. Alternatively, start a fresh conversation and explicitly ask it to read the checked handoff. Repeating the same huge read after every summary recreates the problem; the context-management guidance describes that failure mode.

The following replay uses a separate, illustrative export task. Try continuing, compacting, and starting fresh. Its outcomes are constructed examples of the tradeoffs, not promises about which details your model will retain.

An illustrative session, played back with its context window x-rayed. Watch what the work costs on the right; when the playback pauses, you decide what the session does next - then replay the other choices.

0k / 200k

Fixed overheadRulesConversationFile readsTool outputSummaries

agent session - billing-app

agent cli · new session · repo: billing-app

the window, x-rayed

Every number is an illustrative order of magnitude, and the commands answer to different names across tools - /compact, /compress, or /summarize; /clear, /new, or a fresh chat. The outcomes are constructed possibilities, not predictions. Choose based on the task and verify what survives.

The decision also works without the replay. Continuing carries the existing discussion. Compaction carries a summary that needs checking. A fresh conversation needs the task supplied again, with the relevant files or handoff. Each can be appropriate; the size of the window alone does not choose for you.

Leave the next session something it can check

Finish by asking a fresh or compacted session to locate the health implementation and explain why both addresses matter. Compare its answer with your handoff and source. That is a practical test of continuity. It is more useful than ending with a claim that every feature in the payments service is finished.

You can now choose what history to carry into the next task. There is a separate choice still to make: which actions the agent can perform once it has that context. A perfect handoff does not grant or restrict file access. The next chapter examines permissions and modes.