How to Manage Claude Code Sessions: Resume, Clear, Branch

A Claude Code session is not just a chat transcript — it's a transcript scoped to the directory you started it in. Run claude inside billing-service and every message, tool call, and tool result from that conversation gets written continuously to a session file associated with that project, independent of whether you exit cleanly, close the terminal, or the process crashes. That persistence is what makes everything else in this article possible: resuming, clearing, branching, and picking a session by name all operate on that saved state, not on something reconstructed from your shell history.

The directory scoping matters more than it looks like at first. Session lookup — by --continue, by --resume <name>, by pasting a raw session ID — is scoped to the current project directory and its git worktrees. Run claude --resume BILL-451 from billing-service and it resumes directly; run the identical command from an unrelated repository and Claude Code reports No conversation found with session ID: <id>, because it never looked in the right place. This isn't a bug to work around — it's the same boundary that keeps an unrelated project's sessions out of your picker by default.

One consequence worth internalizing early: /clear does not delete the conversation it clears. It saves the previous conversation and starts an empty one in the same running process, so "I cleared and lost everything" is almost always recoverable with /resume. What's genuinely destructive is different — closing a session that was never named, in an unclean way, on top of an auto-cleanup window (cleanupPeriodDays, 30 days by default) that eventually prunes old transcripts you never returned to.

Four entry points cover almost every case. claude with no flags starts a new session in the current directory. claude --continue (short form -c) resumes the most recent session for the current directory with no picker and no session ID required — the fastest path back into whatever you were just doing. claude --resume, with no argument, opens an interactive picker listing sessions for the current repository, sorted by recent activity, with metadata like time since last activity, git branch, and file size; the same picker opens mid-session by typing /resume. claude --resume <name> skips the picker and resumes that session directly if the name matches exactly, or opens the picker pre-filtered to that search term if it doesn't.

For BILL-451, day one looks like claude -n bill-451 to start a named session (or /rename bill-451 partway through if you forgot). Day two, from the same billing-service checkout, claude --continue picks it back up without you typing the name — useful when it's the only thing you were doing there. Once you're juggling two or three tasks in the same repo, claude --resume bill-451 or the picker becomes the more reliable habit, since --continue only ever knows about "most recent," not "the one I mean."

Naming pays for itself quickly. An unnamed session gets an AI-generated title from your first prompt and a directory-plus-suffix default display name — neither is a resume handle, so claude --resume with that generated title won't match. Only a name you set with -n/--name at launch, /rename mid-session, or Ctrl+R in the picker becomes something you can resume by name later.

Transcripts are stored as JSONL — one JSON object per line, per message, tool call, or metadata entry — at ~/.claude/projects/<project>/<session-id>.jsonl, where <project> is your working directory path with non-alphanumeric characters replaced by dashes. That format is internal and changes between Claude Code releases, so a script that parses these files directly can break on any update; if you need session data programmatically, use /export for a human-readable transcript, or claude -p --resume <session-id> --output-format json "your question" to get a structured answer from an existing session without touching the raw file. The storage location is configurable via CLAUDE_CONFIG_DIR, retention via the cleanupPeriodDays setting, and you can suppress transcript writes entirely with CLAUDE_CODE_SKIP_PROMPT_HISTORY or, per non-interactive run, --no-session-persistence.

A resumed session restores more than the raw text: the full conversation history including tool calls and results, the model it was using (unless that model was retired, isn't allowed by your account's availableModels, or a --model flag overrides it at launch), and the permission mode it was in — with one exception. plan and bypassPermissions modes are never restored automatically; if a session depended on bypassing permission prompts, you re-enable that explicitly at launch, because a resume silently reactivating an unattended, no-prompts mode is exactly the kind of surprise a permission system exists to prevent.

What does not come back automatically is anything tied to how the process was launched rather than to the conversation itself: --mcp-config, --settings, --plugin-dir, --fallback-model, and directories added with --add-dir all need to be passed again if the resumed work depends on them. Standard settings files (settings.json, settings.local.json) are the exception — they're re-read fresh at launch, so configuration that lives there doesn't need repeating. For BILL-451, if day one's session connected an MCP server that reads the PDF template repo, day two's claude --continue needs the same --mcp-config flag again, or that tool silently isn't there and the model has to ask you for a substitute.

These three look similar from the outside — all of them reduce what's in front of the model — but they trade different things away. /clear is the cheapest and safest: it doesn't touch what's already on disk, it just gives you an empty window in the same running process, and the old conversation is one /resume away if you clear the wrong thing. /compact is lossy by construction — it's a real summarization pass, not a lossless index — so a constraint mentioned once early in a long session ("don't touch the legacy PDF renderer, it's still used by the mobile app") can get compressed away if nothing reinforced it later. That's the practical argument for putting durable rules in CLAUDE.md instead of only stating them mid-conversation: CLAUDE.md reloads fresh every session, where a mid-chat instruction is exactly the kind of content a compaction pass can condense away.

A brand-new session is the right call more often than it feels like in the moment. Claude Code's own guidance after two failed correction attempts on the same issue is blunt: the context is now polluted with failed approaches, and a clean session with a better, more specific prompt that incorporates what you learned usually beats continuing to argue inside the cluttered one. For BILL-451, if the model gets stuck trying three wrong regexes to extract a PDF field and you've corrected it twice, that's the signal — not a fourth correction, but /clear and a prompt that states the extraction rule directly instead of hoping the model rediscovers it.

One more distinction worth keeping straight: automatic compaction and /compact are the same mechanism, just triggered differently — Claude Code compacts on its own as the transcript approaches a size threshold, and /compact <instructions> runs the identical summarization on demand, optionally steered (/compact focus on the API changes, drop the exploration). Neither one resets the working directory or any file already edited; only the conversation shrinks, never the code state.

Running more than one Claude Code conversation against the same repository is common — a second opinion on a diff, an unrelated bug fixed in parallel, or a risky rewrite you don't want to commit to yet. The mechanism you pick determines whether the two conversations collide. Resuming the exact same session from two terminals without forking is the one to avoid by default: both processes write to the same transcript, so messages from each interleave into one file, and neither Claude instance has a coherent view of what the other just did. /branch <name>, run from inside a session, avoids that by copying the conversation so far into a new session with its own ID and switching you into it — the original is untouched on disk and still in the picker. From the command line, the equivalent is claude --continue --fork-session or claude --resume <name> --fork-session. Branching is a conversation fork, not a filesystem fork: both the original and the branch still point at the same working directory, so simultaneous file edits from both can still collide.

For actual filesystem isolation, use a worktree: claude --worktree pricing-fix creates a new git worktree — a separate checkout on its own branch, sharing the same repository history — and starts a session there. Now two Claude Code processes can genuinely work in parallel without either one's edits touching the other's files, which is the right setup for BILL-451's invoice migration running alongside an unrelated hotfix. A resumed session that started inside a worktree returns to that same worktree automatically, whether you resume interactively, with -p, or through a fork; a fork that started outside a worktree starts in the directory you launched from, since there's no worktree of its own to return to.

For the multi-day shape of BILL-451 specifically: name the session on day one, resume it by name each morning rather than re-explaining the migration from scratch, and treat git commit as the durable checkpoint, not the session state — checkpoints inside Claude Code (its own automatic per-turn snapshots, or /rewind) recover conversation and file edits made through Claude's own tools, but they are not a replacement for git, and don't capture changes made through Bash commands or external processes. A session resumed after a long gap (roughly an hour of inactivity past 100k tokens) will offer to resume from a compacted summary rather than the full history — useful on day three of a five-day migration once the early exploration no longer matters, and worth declining ("resume full session as-is") on a day when you specifically need to recall an earlier decision verbatim.