A Change Too Big for One Session

How to carry a multi-step change across several Claude Code sessions by keeping its plan, decisions and progress in committed files. It covers continue and resume, reading /context, compaction and what it loses, and a deliberate fresh start, plus recent fixes to resuming and compaction. Episode page & show notes Visit website A change that outlasts one sitting The conversation with Claude Code is not memory you can rely on. The repository is. The worked example is a done checkbox for items in the shared-list app. It needs a schema migration, a way to set the flag through the database client, a checkbox and crossed-out style in the React interface, and tests. The check at the end is to tick an item, reload the page, and see it still ticked. Planning happens in plan mode. The plan goes into a committed file of numbered steps, each with a check that proves it is done. A second file records decisions and rejected options, such as choosing a boolean column over a status text field because the app has only two states and a boolean cannot hold a typo. Stopping halfway and coming back After two committed steps the session ends. claude --continue reopens the most recent session. claude --resume opens a picker with preview, rename and filter, all described in the guide to managing sessions. Resuming restores the conversation, tool results, model and recent checkpoints. It does not restore launch-time folders or elevated permission modes. It also brings back stale guesses and knows nothing of hand edits made since. When the context window fills /context breaks usage into messages, memory files, tool schemas and skills, and the messages row is the one that grows. Compaction replaces older turns with a summary. The root CLAUDE.md is reread and the active goal survives, but exact names and the reasons behind decisions tend to get lost. You can steer the summary with instructions after /compact or with a compact instructions section in CLAUDE.md. A summary is still written by the model. When it and the committed decisions file disagree, the file wins. A deliberate fresh start The handoff has four steps: Have the agent update the progress file. Check each tick against git log and the code. Commit the file. Run /clear. The new session reads the task files, git log and the diff, then reports the state of the work before editing anything. If its account is wrong, the gap is in the files. Keep plans to steps and checks. Rules for every task go in CLAUDE.md, and notes for one task go in the task files. Auto-memory stays on your machine and is not committed, so it cannot replace the task files. Recent fixes to resume and compaction The Claude Code changelog records several relevant changes: 2.1.274: Resuming a compacted session no longer drops its goal. Goal- or hook-driven sessions compact instead of crashing with "prompt too long" on the second overflow. Damaged transcripts are repaired, or resume stops with an error that suggests rewinding. 2.1.282: Resuming long sessions is faster. This does not make the session aware of edits made after it last looked. Context accounting: Tool-server instructions now get their own row in /context. 2.1.283: Compaction shows an elapsed timer and a live count of summary tokens. Claude Opus 5.5 defaults to a one-million-token window, so auto-compaction triggers later, which makes the handoff habit more important.