Closing a Claude Code session well

The simple version

Picture a workshop. You spend the day at one bench making something. By evening the bench is covered in tools, off-cuts, sketches, notes.

/compact is like sweeping the bench mid-day. You push the mess into a tidy pile so you have room to keep working. The pile is still on your bench. The moment you leave the workshop, that pile is gone.

/init is like writing a manual for the workshop. Someone walks around and writes "the chisels live here, the saws live there." It's not for today's project. It's for next week, when you've forgotten where everything is.

Neither one closes the workshop. To actually close up for the night you have to put the tools back (commit), lock the door (push), update the wall map with what changed today (edit CLAUDE.md by hand), and write tomorrow's to-do list (Todoist or similar). Then you leave.

How it actually works

/compact — context, not persistence

/compact is a mid-session move. As you work, your conversation grows. Every exchange — every file read, every tool call, every reply — eats into Claude's context window. Past a threshold, responses slow down and the model starts compacting for you.

/compact lets you do it deliberately. The conversation up to that point gets summarised into a smaller blob, freeing space for new work. It is purely in-session optimisation. Nothing reaches disk. The summary lives in the conversation and dies when the conversation ends.

When it helps:

• You're mid-flow and crossed ~60% context
• You've done heavy exploration and want only the conclusions kept
• You're about to start a big new sub-task in the same session

When it doesn't:

• You're under 30% — no benefit, just losing nuance
• You're about to close the session anyway — pointless, it doesn't persist

/init — analysis, not journal

/init reads your codebase (file tree, manifests, key entry points) and writes a CLAUDE.md describing what it found: stack, commands, architecture, file purposes. It's a code-shape document, not a conversation log.

That's where the trap is. If your CLAUDE.md has hand-written sections — status, decisions, gotchas, "we tried X but pivoted to Y" — /init doesn't know about those. Re-running it can wipe out the most valuable parts of the file.

When it's right:

• Brand-new project with no CLAUDE.md yet
• Major architectural reshape where the existing doc is meaningfully wrong

When it's wrong:

• Any project where you've been curating CLAUDE.md for weeks or months
• You just want to capture today's decisions — that's an edit, not an /init

What actually persists

Nothing in Claude Code auto-saves your conversation to a permanent place. If today's session decided to switch from Postgres to SQLite, that decision exists only in the code you wrote and whatever you explicitly captured. Close the session without writing it down and the next session won't know.

Session-end persistence is a checklist, not a command:

1. git add + commit + push
   → code state is durable, off this machine
2. Hand-edit CLAUDE.md
   → status changes, decisions, gotchas discovered
3. Capture cross-project learnings to memory
   → things bigger than this one project
4. Update task tracker (Todoist, Linear, GitHub issues)
   → what's next, what's blocked
5. Close the session

Step five matters. Long-lived sessions feel efficient but rarely are — context decay never gets captured, the conversation gets expensive to re-process, and you tend to keep tweaking instead of shipping.

Why close instead of keeping it open

A fresh session forces three useful behaviours:

• Discipline. You can't close cleanly without writing things down. Future-you wins.
• Cheap context. New sessions don't carry yesterday's transcript. They start lean and fast.
• Deployable state. Closing requires committed code, which means the repo is always shippable.

The exception is loop-style work — scheduled tasks, polling, long-running monitors — where the session lifetime is the loop. For normal feature work or research, close at the natural finish line, not "when the screen gets full."