Session Hygiene

A Claude Code session accumulates context with every prompt: file reads, tool results, half-finished diffs, abandoned approaches. Past a certain length, the session starts costing more and producing less — token usage climbs, output quality drops, and the model starts confidently referring to files or decisions that aren’t actually current.

Session hygiene is the discipline of ending sessions at the right time, pausing cleanly, and resuming without forcing the new session to reconstruct what happened. The git repo is the persistence layer; Claude Code sessions are disposable.

When to end a session

Three signals that a session has run its course:

• The current task is done and committed. Don’t roll into the next feature in the same session — the previous task’s context is now noise.
• Output quality is dropping. If Claude Code starts forgetting recent decisions, suggesting things you already rejected, or referring to files in stale states, the session is past its useful life.
• You’re about to switch context. A frontend bug fix and a Supabase migration are different jobs. Two sessions, not one.

The rule of thumb: one feature, one session. Bootstrap is its own session. The PRD pass is its own session. Each feature build is its own session.

Pausing for the day

When you stop for a break — end of day, end of focus block, anything that involves closing the terminal — there’s nothing special to do inside Claude Code. The work just needs to be committed and pushed:

git add . && git commit -m "WIP: [where you're up to]"
git push

Then close the terminal. The WIP: prefix matters when you’re stopping mid-prompt — it’s a signal to the next session that the commit isn’t a finished feature, just a checkpoint.

If memory.md hasn’t been updated this session and you’ve made decisions worth recording, ask Claude Code to append an entry before you close. Without it, the next session has less to read on the way back in.

Resuming a paused project

Open the terminal, navigate to the project, and start a fresh Claude Code session:

cd ~/projects/[project-name]
claude

Then paste a re-orientation prompt as the first message:

I'm building [Project Name]. Read docs/prd.md and PLAN.md for context.
Check git log --oneline to see what's already been built.
Then tell me what the last completed step was and what comes next.

Do not write any code yet.

Claude Code reads the git history, sees the commits, and orients itself against the PRD and plan. You pick up from wherever you left off.

If you stopped mid-prompt and the last commit was a WIP:, point Claude Code at the partial work directly:

The last commit was a WIP. Check the current state of [the file you were working on]
and tell me what's done and what's missing before we continue.

The whole ritual is: commit, push, close. Reopen, relaunch, re-orient. Each session opens with clean context and the git repo carries everything that matters between them.

Migrating a stale session to a fresh one

Pausing and resuming covers the routine case. The other case is when a session is genuinely useful — you’re mid-task, you’ve made progress, but the context is bloating and quality is dropping. You want to keep the work in flight, not pause it.

Before closing the stale session, ask Claude Code to produce a migration prompt:

I'm starting a fresh session to continue this work with clean context.
Write a single prompt I can paste into the new session that captures:
- What we've completed in this session
- What's in progress and where it stands
- Any decisions made that aren't yet in memory.md
- The single next step

Keep it under 300 words.

Paste the result into the new session as the first message. The new session opens with the relevant context and none of the accumulated noise. This is heavier than a normal re-orientation because the work isn’t committed yet — the migration prompt has to carry the in-flight state that the git repo can’t.

What not to do

• Don’t keep one chat running for a whole project. Long chats dilute output quality. Three short sessions are better than one long one.
• Don’t skip the WIP: commit on the way out. Without it, the next session can’t tell what’s a finished feature and what’s a checkpoint.
• Don’t migrate context for trivial reasons. If the next task is independent of the current one, just start fresh — no migration prompt needed.
• Don’t skip the memory.md update on the way out. This is the recoverable record. Without it, the Resurrector sub-agent has nothing to read.