Session craft: when to start fresh, resume, or compact

TLDR; Claude Code session management means treating each session as a limited resource. Quality drops well before the session fills up, so run /clear between unrelated tasks, keep plans in files, commit before Claude works alone, and use /rewind to undo a wrong turn. Run parallel sessions in separate working copies when streams of work are independent. I have replaced /compact with a written handoff file and /clear.

When to manage your Claude Code session

• A task is ending and the next one is unrelated. Switching clients, leaving the backend for the frontend, or starting a bug fix after a feature.
• Claude repeats itself. It suggests something you ruled out two exchanges ago, or misses an instruction you already gave.
• A long job will run on its own. Several files, a failing test suite, or a plan Claude works through alone.
• You want to run two or three streams of work at once.
• Skip it for a task you will finish in minutes. A small task rarely fills enough of the window to reach the tail where quality drops.

How Claude Code session management works

The context window limits a session. It is the amount of text Claude can hold at once, counted in tokens: small fragments of text, roughly half a word each. Every session starts with overhead before you type a word. The system prompt takes a few thousand tokens. Three more things load on top. Your CLAUDE.md files hold standing instructions Claude reads at the start. Connected MCP servers (add-on tool providers) add their tool names. Auto-memory adds notes Claude keeps for itself across sessions. Run /context in a fresh session to see your own breakdown, because published figures change with every release.

On my setup, a 200,000-token window leaves 145,000–167,000 tokens of working space. Current default models run a 1M-token window and auto-compact (summarise the conversation automatically) near 967K. A larger window raises the limit but changes none of the habits below, because Claude still tracks detail less reliably as the window fills.

The window fills fast. On my setup, a typical file read runs 500 to 2,000 tokens, and a test suite’s output can be 5,000 or more.

Quality drops gradually. The “lost in the middle” paper tested long-context retrieval and question answering. On those tasks, models often used information in the middle less reliably than information near the start or end. It sets no universal threshold for Claude Code. It does explain why long sessions need checking.

Auto-compact’s trigger changes by model and release. On my setup, by the time it fired, it was often too late for a clean handoff. These phases are from my own tracking, not product guarantees:

• Fresh (0–40% of the window used): Claude follows all instructions and remembers everything.
• Working (40–65%): still effective. Choose between compacting and clearing.
• Degrading (65% and up): missed instructions, repeated suggestions, contradicted decisions. Act now or pay in rework.

Three commands answer three problems.

// THREE COMMANDS, THREE PROBLEMS

1. /compact

   • To keep going in the same thread
   • Run before quality drops

2. /clear

   • For context that’s no longer relevant
   • Between unrelated tasks

3. /rewind

   • For recovery
   • Go back to a specific point

How to manage a Claude Code session

1. Clear between unrelated tasks

In my experience, /clear is the most underused command in Claude Code. It wipes the conversation and gives you a clean window. Setting the task up again costs tokens.

I clear between every unrelated task. Finish a feature, commit it, /clear, start the bug fix. Carrying the feature’s context into the fix fills the window faster and makes Claude likelier to mix up instructions from the two jobs.

Reloading your CLAUDE.md and reading a few key files costs roughly 3,000–5,000 tokens. That is small next to a degraded 150,000-token session in which Claude has lost track of the work. My rule: if the next task doesn’t need this one’s context, clear. It applies after a long debugging session (the failed attempts are noise) and after a commit (the details are in git now).

When Claude suggests something you ruled out two exchanges ago, the session has degraded. Don’t correct it. Clear and restart: three minutes setting up again beats twenty minutes of arguing.

Boris Cherny, who created Claude Code, treats sessions as disposable. According to a fan-made collection of his posts, he runs about five local sessions, each in its own git checkout (a separate copy of the code), plus more on the web. Each session works on one task and keeps its window lean. The official best practices say the same: short, focused sessions beat long, sprawling ones.

Check: after you give the new session its brief, it can name the task and the files in play.

2. Resume only what is costly to rebuild

claude --continue picks up your most recent session. claude --resume lets you choose from a list. Both reopen the saved conversation. If it was compacted, Claude continues from the summary.

Resume when you spent real effort building context. Say you spent fifteen minutes explaining six Active Record models (Rails database classes), how they link to each other and the edge cases in their validation rules. That explanation cost tokens, and starting fresh means paying for it again.

Judge freshness before you resume. I resume a session from earlier today without hesitation, one from yesterday if the files haven’t changed, and one from three days ago almost never. Code changes between sessions open a gap between what Claude remembers and what is on disk, and that gap produces subtle bugs.

To try another approach without losing the original, fork the session. In a running session, /branch copies the transcript, switches you into the copy and leaves the original untouched. From the command line, claude --continue --fork-session does the same for your most recent session. /branch stays in the running session, so permissions you approved for this session still apply. --fork-session starts fresh and asks for approvals again.

Check: Claude has reread the files that changed since the session stopped (git log and git status show what changed), and its account matches them.

3. Keep plans and decisions in files

Conversations compress. Files don’t. Early in a complex feature, ask Claude to write the implementation plan to a Markdown file, and have it update the file as you decide things:

Write the plan to docs/plan-invitations.md: the decisions so far, the
files we will touch, and what is still open. Update it whenever we
settle something.

After a compaction, or in a fresh session the next day, tell Claude to reread the file, and it picks up where you stopped. The memory hierarchy guide covers where each kind of fact belongs. The tech-lead guide covers planning in full, including keeping task state in the repository so a commit carries code and state together.

Check: a fresh session, told only to read the file, can state the open decisions.

4. Compact with intent, or hand off instead

/compact summarises the conversation to free space. It drops detail by design, and what survives depends partly on what you tell it to keep. Unguided, the summary keeps what Claude guesses is important, so a decision you made forty minutes ago can shrink to one line or vanish. Guide it:

/compact Preserve: the API endpoint naming convention (kebab-case,
versioned under /api/v1/), the pagination approach (cursor-based,
not offset), and the three test failures we haven't addressed yet.

Don’t wait for auto-compact. I used to compact by hand at roughly 50,000 free tokens remaining, about 75% used on a 200K-window model. That is a personal threshold, not a documented quality boundary. To trigger auto-compact earlier, set an environment variable:

export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=65

This fires compaction at 65% of the auto-compact window. Per Anthropic’s environment variable docs, it applies to any session that compacts before the model’s context limit, including default 1M-token sessions that auto-compact near 967K. In my testing, 65–70% works well. Check that it fires at your threshold before you rely on it. Recent versions also accept /autocompact 500k, which sets the auto-compact window in tokens for the current model.

Verify afterwards. Ask about a decision that matters: “What pagination approach did we agree on?” If Claude can’t answer, the compaction lost it. Rewind (step 5) or start fresh with a clear brief.

I now write a handoff, then run /clear. The model writes a compaction summary for itself, and it never shows in my terminal. A handoff is a file I can read and correct before the next session acts on it. It also survives a crashed terminal. At a task boundary, ask the session to write one:

Write a handoff to .claude/handoffs/<branch>.md: the decisions and why
we made them, what we tried and what failed, where things stand, and
the one next action. Then I will run /clear.

After /clear, tell the new session to read the file. A SessionStart hook (a script Claude Code runs when a session begins) can load it for you.

Scroll sideways →

/handoff is my own skill (see In practice); the prompt above does the same job. /compact still works when you want to keep going in the same thread; I hand off instead.

Check: you have read the handoff, or asked the compacted session to list the open decisions, and every one is there.

5. Rewind a Claude Code session when a turn goes wrong

A turn is one prompt and Claude’s reply. Press Esc twice on an empty prompt to open /rewind, or type the command. It lists every prompt in the session. Pick a point, then choose what to restore.

When Claude references methods that don’t exist or contradicts your decisions, restore the conversation only: it goes back to the last good prompt, and the working code stays. In a refactor (restructuring existing code), if each change works on its own but the whole fails, restore the code only: the files roll back, and the conversation keeps the failed attempt and what you learned from it. Where /clear throws context away on purpose, /rewind recovers context you didn’t mean to lose.

// WHAT /REWIND CAN RESTORE

Option	Files	Conversation	Use when
Restore code only	Reverted	Kept	Claude understood the task but the implementation broke
Restore conversation only	Kept	Rewound	The files work but Claude has lost track of your decisions
Restore both	Reverted	Rewound	The experiment didn’t pan out
Summarize from here	—	Kept up to the chosen point, summarised after it	The early setup matters; the debugging after it is bloat
Summarize up to here	—	Summarised up to the chosen point, kept after it	A long, settled preamble is crowding the thread

Follow a rewind with a sharper prompt that uses what the failed attempt taught you.

/rewind tracks edits made through Claude’s file-editing tools. It doesn’t restore a file that only bash changed (rm, mv, cp, or a command that rewrites a file), so commit before Claude runs a destructive shell command. It never touches a database either: a migration (a scripted database change) that drops a column is permanent. Edits you make in your own editor aren’t tracked, though a rewind can overwrite them in a file Claude also edited. Edits by sub-agents (helper sessions Claude starts for one job) aren’t restored unless Claude had already edited the same file. The exception is a skill that forks a helper in the foreground: its edits are restored. On restore, /rewind skips symlinked and hard-linked files (shortcuts to other files) and warns you.

/rewind returns to saved points called checkpoints. They survive a resumed session. Claude Code keeps file snapshots for the 100 most recent checkpoints and by default deletes them about 30 days after the session last saved one. They are an undo for one session and do not replace git: use checkpoints for mid-task experiments and commits for milestones.

Check: what you restored (code, conversation or both) matches the point you chose.

6. Commit before Claude works alone

A commit is a rollback point. If the next task goes wrong, inspect the diff and restore the files you want from that commit. git checkout . restores only files git already tracks and leaves new ones behind, so it is not a full rollback.

The rhythm is explore, plan, code, then commit. First let Claude read the files. For anything non-trivial, press Shift+Tab until the mode reads Plan. In Plan Mode Claude reads and plans but writes no code. In my experience, well-planned tasks often finish in a single pass. Planning saves context too: five minutes in Plan Mode can save twenty minutes of corrections, and the tokens they would have used.

This matters most when Claude runs unattended. After a mistake deep in a long session, the context is cluttered with the failed attempt, and fixing it there usually produces more mistakes. Roll back to the commit and start a fresh session with a refined prompt. Anthropic’s best practices make the same point: “A clean session with a better prompt almost always outperforms a long session with accumulated corrections.” In a short session, /rewind to the prompt before the task does the same job.

// COMMIT, RUN, REVIEW, REWIND

1. Give Claude the taskLet it run
2. Review the resultGood? Commit and continue
3. Bad? /rewindTo the clean state; try again with a better prompt

Commit clean stateYour rollback point

After /rewind, give Claude the task again with a better prompt.

Check: git status --short prints nothing before you hand Claude the task.

7. Run parallel Claude Code sessions in worktrees

Instead of managing one long session, you can run several short ones. claude --worktree (or -w) creates a git worktree for each session: a separate checkout of your repository on its own branch. Each session works in its own copy, so their edits don’t collide, and each keeps a clean window.

# Terminal 1
claude -w feature-invitation-model

# Terminal 2
claude -w feature-invitation-tests

# Terminal 3
claude -w feature-invitation-docs

While one session runs a ten-minute task, work in another. When they finish, merge each branch after the ones it depends on. Resolve conflicts (usually in routes or configuration files) and run the full test suite on the result.

The incident.io engineering team barely used Claude Code at first. Four months after Claude Code’s announcement, it had four or five Claude agents running at once. A fan-made collection of Boris Cherny’s posts calls parallel worktree sessions his biggest productivity gain, and the top tip from the entire Claude Code team.

I run two or three worktree sessions per feature; beyond that, tracking them costs more than they save. The right number depends on how independent the work streams are.

Start with worktrees. Claude Code also has agent teams, an experimental feature in which sessions coordinate through shared tasks under a team lead. They cost more, and they are worth it only when the work needs that coordination. The multi-agent orchestration guide covers cost modelling, briefing patterns and a case study with token breakdowns.

Check: each session runs on its own branch (git branch --show-current in each terminal), and the merged branch passes the full tests.

Pitfalls

In practice

The first time Claude Code auto-compacted on me mid-task, I lost twenty minutes of context. I was deep in a client’s API refactor. We had settled the endpoint naming convention, agreed the pagination pattern and mapped four controllers (the code that handles each request). The window filled, auto-compact fired, and Claude forgot the pagination decision. It suggested the approach we had already ruled out.

At a task boundary, or around 50 turns, I now run a /handoff skill I wrote, then /clear. The skill and its hooks ship in hamster, my open-source plugin, which also turns repeated mistakes into hook rules. I used to compact by hand 35–40 times a week. In the five weeks after I switched, I didn’t compact once in the last three, and no session ran past 50 turns.

My global CLAUDE.md used to say /compact if the next task is related and /clear if it isn’t. A review of my sessions changed that. It now says /handoff then /clear, never /compact, because a handoff file carries the related context forward without a summary that drops detail.

I find rules like that with a /review-session command I run after a large piece of work. It reads the conversation and reports where I wasted context. Typical findings: re-explaining a constraint that belonged in CLAUDE.md, exploring in the main session when a sub-agent would have been cleaner, compacting without preservation instructions. Each finding comes with an offer to fix the cause with a CLAUDE.md line, a skill or a hook. Over three months of these reviews, my sessions have run longer before degrading, and the cost per session has stayed flat while the work per session has grown.

When I join a team as a fractional CTO and everyone uses Claude Code their own way, one of my first jobs is to agree a shared session routine.

---

Related reading

• How to write a CLAUDE.md file for Claude Code, the instructions every fresh session reloads
• Claude Code memory, where decisions live so a fresh session can find them
• The tech-lead pattern, plans and briefs written to files before code
• Claude Code skills, hooks, subagents and commands: when to use each, the building blocks that automate session routines
• Multi-agent orchestration, running parallel agents on real projects, the full parallel execution model with cost data
• Claude Code pricing: what plans, tokens and models cost, understanding the cost model behind context management
• Claude Code hook examples: turning mistakes into tested rules, the open-source plugin that ships the handoff skill
• 10 ways to reduce Claude Code token usage, practical techniques for session efficiency

Sources

• Lost in the Middle: How Language Models Use Long Contexts, Liu et al., 2023. Tests how models use information at different positions in long inputs. Academic paper
• How Boris Uses Claude Code, Boris Cherny’s parallel session workflow and productivity patterns. Secondary source (fan-made collection)
• Best Practices, Claude Code Docs, Official Anthropic guidance on session management and workflow. Documentation
• Environment variables, Claude Code Docs, CLAUDE_AUTOCOMPACT_PCT_OVERRIDE and when it applies. Documentation
• How we’re shipping faster with Claude Code and Git Worktrees, incident.io engineering team on scaling parallel worktree adoption. Case study
• Checkpointing, Claude Code Docs, Official documentation on /rewind, restore modes, and the limitations around bash-modified files. Documentation

Common questions

When should you start a fresh Claude Code session?

When the task changes, or when the session is full of work that no longer helps. Run /clear between unrelated tasks. A fresh start costs roughly 3,000 to 5,000 tokens (small units of text) to reload your instructions and orient Claude. A long session that has lost track of the work costs more.

When should you compact a session instead of starting over?

Compact when the thread is still relevant but long. /compact asks Claude to summarise the conversation so far and free space. Start fresh when the next task is unrelated. A handoff file plus /clear keeps what matters: the file records the decisions, what failed and the next action, and the new session reads it.

How do you resume a Claude Code session?

`claude --continue` reopens your most recent session, and `claude --resume` lets you pick one from a list. Resume one only if the code hasn’t changed since it stopped, or ask Claude to reread the files that changed. Otherwise Claude works from an out-of-date picture of the code.

How do you run Claude Code sessions in parallel?

Start each one with `claude -w <name>`. Each session gets its own git worktree, a separate copy of the code on its own branch, so the sessions’ file edits don’t collide.

How do you stop session quality from degrading?

Clear between tasks, keep plans and decisions in files rather than in the chat, commit before Claude works on its own, and use /rewind (Claude Code’s undo command) to go back when a turn goes wrong. A long conversation loses detail in the middle, so a clean session with the facts written down beats a long one.