Never lose your context again. A complete end-to-end guide to Claude Code session management \u2014 what sessions are, why they matter, every command, and real-world workflows.<\/p>\n\n\n\n
May 2026 ~15 min read Claude Code \u00b7 CLI<\/p>\n\n\n\n
In this tutorial<\/p>\n\n\n\n
--continue<\/code> flag in depth<\/a><\/li>\n\n\n\n- The
--resume<\/code> flag in depth<\/a><\/li>\n\n\n\n- Side-by-side comparison<\/a><\/li>\n\n\n\n
- All session commands & flags<\/a><\/li>\n\n\n\n
- How sessions are stored<\/a><\/li>\n\n\n\n
- Naming sessions with
--name<\/code><\/a><\/li>\n\n\n\n- Forking sessions<\/a><\/li>\n\n\n\n
- Context management with
\/compact<\/code><\/a><\/li>\n\n\n\n- Automation & scripting<\/a><\/li>\n\n\n\n
- Real-world workflows<\/a><\/li>\n\n\n\n
- Troubleshooting<\/a><\/li>\n\n\n\n
- Pro tips & best practices<\/a><\/li>\n<\/ol>\n\n\n\n
01 \u00b7 Foundations<\/p>\n\n\n\n
What is a Claude Code session?<\/h2>\n\n\n\n
A session<\/strong> is the complete conversation history that Claude Code accumulates while working on your code. It is not just the text you typed \u2014 it is everything:<\/p>\n\n\n\n\n- Every prompt you sent<\/li>\n\n\n\n
- Every tool call Claude made (file reads, edits, bash commands)<\/li>\n\n\n\n
- Every tool result returned<\/li>\n\n\n\n
- Every response Claude produced<\/li>\n<\/ul>\n\n\n\n
The SDK writes this record to disk automatically as a .jsonl<\/code> file. Each line is an event \u2014 an append-only stream of everything that happened. Because it is persisted to disk, you can close your terminal, shut down your laptop, come back tomorrow, and load the entire history back in as if you never left.<\/p>\n\n\n\n\u2139<\/p>\n\n\n\n
Important distinction:<\/strong> Sessions persist the conversation<\/em>, not the filesystem. If Claude edited a file during a session, that file change is already on disk \u2014 resuming the session gives Claude memory of having made that change, but does not undo or redo it. For snapshot-and-revert of file changes, use file checkpointing.<\/p>\n\n\n\nWhen you resume a session, Claude has full context from before: files it already read, analysis it already performed, decisions it already made. You can ask a follow-up question, recover from an interruption, or branch off to try a different approach \u2014 all without re-explaining your codebase from scratch.<\/p>\n\n\n\n
02 \u00b7 Motivation<\/p>\n\n\n\n
Why session persistence matters<\/h2>\n\n\n\n
Without session management, every time you invoke claude<\/code> you start with a blank slate. Claude has no idea what you worked on yesterday. You re-explain the architecture, re-describe the bug, re-establish the constraints. This is not just annoying \u2014 it is costly in time and tokens.<\/p>\n\n\n\nWithout sessions<\/p>\n\n\n\n
\n- Re-explain architecture every morning<\/li>\n\n\n\n
- Re-describe the bug context each time<\/li>\n\n\n\n
- Lose decisions made mid-refactor<\/li>\n\n\n\n
- Start fresh after a terminal crash<\/li>\n\n\n\n
- Cannot hand off work to a teammate<\/li>\n\n\n\n
- No audit trail of what Claude changed<\/li>\n<\/ul>\n\n\n\n
With sessions<\/p>\n\n\n\n
\n- Step away for lunch, continue seamlessly<\/li>\n\n\n\n
- Recover from IDE\/terminal crashes<\/li>\n\n\n\n
- Multi-day features stay in context<\/li>\n\n\n\n
- Juggle multiple tasks with separate threads<\/li>\n\n\n\n
- Audit every tool call that was made<\/li>\n\n\n\n
- Branch off to try alternative approaches<\/li>\n<\/ul>\n\n\n\n
03 \u00b7 The first flag<\/p>\n\n\n\n
The --continue<\/code> flag in depth<\/h2>\n\n\n\nWhat it does<\/h3>\n\n\n\n
--continue<\/code> (short form: -c<\/code>) automatically finds the most recent session for the current working directory<\/strong> and resumes it. You do not need to know any session ID. Zero configuration required.<\/p>\n\n\n\nbash<\/p>\n\n\n\n
# Resume the last session in this directory\nclaude --continue\n\n# Short form\nclaude -c\n\n# Resume AND immediately send a prompt (no interactive mode needed)\nclaude -c \"check if the tests pass now\"\n\n# Resume in non-interactive \/ script mode\nclaude -c -p \"Check for type errors\"<\/pre>\n\n\n\nWhen to use --continue<\/code><\/h3>\n\n\n\n1<\/p>\n\n\n\n
You stepped away mid-task<\/h4>\n\n\n\n
You were refactoring an auth module, went to lunch, came back. Just run claude -c<\/code> and ask “where were we?” \u2014 Claude will summarize the last few actions and pick up exactly where it stopped.<\/p>\n\n\n\n2<\/p>\n\n\n\n
Your terminal was killed<\/h4>\n\n\n\n
Session state is written to disk on every event, not on exit. A crash loses nothing. Run claude -c<\/code> to restore the full conversation.<\/p>\n\n\n\n3<\/p>\n\n\n\n
Daily continuation on a single project<\/h4>\n\n\n\n
If you work on one project at a time and want to just keep going each morning, --continue<\/code> is the zero-friction way to do it. No IDs, no lists \u2014 just continuity.<\/p>\n\n\n\n\u26a0<\/p>\n\n\n\n
Non-interactive mode caveat:<\/strong> When using --continue<\/code> with -p<\/code> in scripts, it may sometimes create a new session instead of resuming. For reliable automation with a specific thread, use --resume<\/code> with an explicit session ID or name instead.<\/p>\n\n\n\n04 \u00b7 The second flag<\/p>\n\n\n\n
The --resume<\/code> flag in depth<\/h2>\n\n\n\nWhat it does<\/h3>\n\n\n\n
--resume<\/code> (short form: -r<\/code>) resumes a specific<\/em> session. You either pass a session ID, a session name, or nothing (to get an interactive picker of all recent sessions).<\/p>\n\n\n\nbash<\/p>\n\n\n\n
# Open interactive picker \u2014 browse all recent sessions\nclaude --resume\n\n# Resume a session by its ID\nclaude --resume abc123def456\n\n# Short form with ID\nclaude -r abc123def456\n\n# Resume a named session\nclaude --resume \"feature-auth-system\"\n\n# Resume a named session + immediately send a prompt\nclaude -r \"payment-integration\" \"Finalize the Stripe webhook handler\"\n\n# Resume a specific model version alongside\nclaude --resume abc123def456 --model opus<\/pre>\n\n\n\nThe interactive picker<\/h3>\n\n\n\n
Running claude --resume<\/code> with no arguments opens a rich interactive list. The picker shows session summaries, message counts, git branch names, and timestamps. You can:<\/p>\n\n\n\n\n- Press
A<\/code> to toggle between current directory and all projects<\/li>\n\n\n\n- Press
B<\/code> to filter by your current git branch<\/li>\n\n\n\n- Search by session name<\/li>\n<\/ul>\n\n\n\n
When to use --resume<\/code><\/h3>\n\n\n\n1<\/p>\n\n\n\n
Multiple concurrent tasks<\/h4>\n\n\n\n
You have a “bugfix-payment” session and a “feature-new-dashboard” session running in parallel. --continue<\/code> only gets you the most recent one. --resume<\/code> lets you switch between them precisely.<\/p>\n\n\n\n2<\/p>\n\n\n\n
Returning to a session that is not the most recent<\/h4>\n\n\n\n
You started a multi-week feature branch. You have done other sessions since. --resume \"feature-user-auth\"<\/code> takes you straight back to that thread without hunting through history.<\/p>\n\n\n\n3<\/p>\n\n\n\n
Cross-directory session access<\/h4>\n\n\n\n
By passing an explicit session ID, you can resume a session originally created in a different project directory. This is called “session archaeology” \u2014 recovering valuable older conversations.<\/p>\n\n\n\n
4<\/p>\n\n\n\n
Reliable automation & CI\/CD<\/h4>\n\n\n\n
Scripts that capture a session ID can pass it back to --resume<\/code> on subsequent runs for guaranteed continuity, unlike --continue<\/code> which may create a new session in non-interactive mode.<\/p>\n\n\n\nUsing \/resume<\/code> inside a running session<\/h3>\n\n\n\nYou do not have to exit Claude Code to switch sessions. Type \/resume<\/code> during any conversation and the same interactive picker appears. Perfect when you are bouncing between tasks and realize you need context from a different thread.<\/p>\n\n\n\n05 \u00b7 Side by side<\/p>\n\n\n\n
–continue vs –resume: the definitive comparison<\/h2>\n\n\n\n
–continue \/ -c<\/p>\n\n\n\n
Zero-config continuation<\/h4>\n\n\n\n
Finds the most recent session in the current directory automatically.<\/p>\n\n\n\n
\n- No session ID required<\/li>\n\n\n\n
- Best for single-task workflows<\/li>\n\n\n\n
- Ideal for daily resumption<\/li>\n\n\n\n
- Minimal cognitive overhead<\/li>\n\n\n\n
- Caution in non-interactive scripts<\/li>\n<\/ul>\n\n\n\n
–resume \/ -r<\/p>\n\n\n\n
Precise session targeting<\/h4>\n\n\n\n
Loads any session by ID, name, or interactive picker.<\/p>\n\n\n\n
\n- Requires ID or name<\/li>\n\n\n\n
- Required for multi-session apps<\/li>\n\n\n\n
- Works across directories<\/li>\n\n\n\n
- Reliable in automation<\/li>\n\n\n\n
- Full session archaeology<\/li>\n<\/ul>\n\n\n\n
Aspect<\/th> –continue<\/th> –resume<\/th><\/tr><\/thead> –continue \/ -r<\/td> Most recent in CWD<\/td> Any, by ID or name<\/td><\/tr> ID tracking needed?<\/td> No<\/td> Yes (or use picker)<\/td><\/tr> Interactive picker?<\/td> No<\/td> Yes (claude –resume with no args)<\/td><\/tr> Works cross-directory?<\/td> No<\/td> Yes<\/td><\/tr> Safe in scripts?<\/td> Sometimes unreliable<\/td> Reliable with explicit ID<\/td><\/tr> Multi-user apps?<\/td> Not suitable<\/td> Required<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n06 \u00b7 Reference<\/p>\n\n\n\n
All session commands & flags<\/h2>\n\n\n\nCommand \/ Flag<\/th> Short<\/th> What it does<\/th> Type<\/th><\/tr><\/thead> –continue<\/td> -c<\/code><\/td>Resume most recent session in current directory<\/td> CLI flag<\/td><\/tr> –resume [id|name]<\/td> -r<\/code><\/td>Resume a specific session or open the interactive picker<\/td> CLI flag<\/td><\/tr> –name <name><\/td> -n<\/code><\/td>Assign a human-readable name when starting a new session<\/td> CLI flag<\/td><\/tr> –list<\/td> \u2014<\/td> List all sessions with IDs, names, and timestamps<\/td> CLI flag<\/td><\/tr> –no-session-persistence<\/td> \u2014<\/td> Disable session saving for a one-shot query<\/td> CLI flag<\/td><\/tr> –output-format json<\/td> \u2014<\/td> Output includes session_id<\/code> field for capturing IDs in scripts<\/td>CLI flag<\/td><\/tr> \/resume<\/td> \u2014<\/td> Open the session picker from inside a running session<\/td> REPL cmd<\/td><\/tr> \/compact<\/td> \u2014<\/td> Summarize conversation history to free context window<\/td> REPL cmd<\/td><\/tr> \/rename <name><\/td> \u2014<\/td> Give the current session a human-readable name<\/td> REPL cmd<\/td><\/tr> \/status<\/td> \u2014<\/td> Show current model, context usage, and session info<\/td> REPL cmd<\/td><\/tr> continue: true<\/td> \u2014<\/td> SDK option (TypeScript\/Python) \u2014 continue most recent session<\/td> SDK option<\/td><\/tr> resume: sessionId<\/td> \u2014<\/td> SDK option \u2014 resume a specific session by ID<\/td> SDK option<\/td><\/tr> fork: sessionId<\/td> \u2014<\/td> SDK option \u2014 create a new session branched from an existing one<\/td> SDK option<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n07 \u00b7 Under the hood<\/p>\n\n\n\n
How sessions are stored on disk<\/h2>\n\n\n\n
Every session is stored locally as a .jsonl<\/code> file (JSON Lines \u2014 one event per line). The file lives inside ~\/.claude\/projects\/<\/code>, in a subdirectory keyed by a hash of the project’s absolute path. This keeps sessions from different projects completely isolated from one another.<\/p>\n\n\n\n~\/.claude\/ \u251c\u2500\u2500 projects\/ \u2502 \u251c\u2500\u2500 -Users-you-project-alpha\/\u2190 hash of \/Users\/you\/project-alpha \u2502 \u2502 \u251c\u2500\u2500 a1b2c3d4-e5f6-7890-abcd-ef1234567890.jsonl \u2502 \u2502 \u251c\u2500\u2500 b2c3d4e5-f6a7-8901-bcde-f12345678901.jsonl \u2502 \u2502 \u2514\u2500\u2500 settings.json \u2502 \u2514\u2500\u2500 -Users-you-project-beta\/\u2190 hash of \/Users\/you\/project-beta \u2502 \u2514\u2500\u2500 c3d4e5f6-a7b8-9012-cdef-123456789012.jsonl \u251c\u2500\u2500 history.jsonl\u2190 global session index \u2514\u2500\u2500 CLAUDE.md\u2190 global memory file<\/p>\n\n\n\n
The encoded directory name is the project path with every non-alphanumeric character replaced by a dash. So \/Users\/me\/proj<\/code> becomes -Users-me-proj<\/code>. This is why resuming from the wrong directory fails \u2014 Claude Code looks in the wrong subdirectory.<\/p>\n\n\n\nWhat each session file contains<\/h3>\n\n\n\n
Each .jsonl<\/code> file is an append-only stream of events. A typical entry looks like:<\/p>\n\n\n\njsonl<\/p>\n\n\n\n
{\n \"sessionId\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n \"startTime\": \"2026-05-08T10:00:00Z\",\n \"lastActive\": \"2026-05-08T11:27:00Z\",\n \"messages\": [...],\n \"fileContext\": {\n \"read\": [\"src\/auth.ts\", \"src\/middleware.ts\"],\n \"modified\": [\"src\/auth.ts\"],\n \"created\": [\"tests\/auth.test.ts\"]\n },\n \"permissions\": {\n \"approvedTools\": [\"Bash(git:*)\", \"Edit\"]\n }\n}<\/pre>\n\n\n\n\u2726<\/p>\n\n\n\n
Sessions do not expire. You can resume any saved session regardless of when it was created. The picker shows them sorted by last activity, with the ability to search by name. The global history is in ~\/.claude\/history.jsonl<\/code> \u2014 each entry includes a sessionId<\/code> and the project path it came from.<\/p>\n\n\n\n08 \u00b7 Organization<\/p>\n\n\n\n
Naming sessions with –name<\/h2>\n\n\n\n
The --name<\/code> flag (short: -n<\/code>), introduced in Claude Code v2.1.76, lets you assign a human-readable name at session start. A good name transforms “abc123def” into “feature-auth-system” \u2014 instantly scannable in the picker.<\/p>\n\n\n\nbash<\/p>\n\n\n\n
# Start a new named session\nclaude -n \"feature-user-auth\"\n\n# Long form\nclaude --name \"bugfix-stripe-webhook\"\n\n# Good naming patterns \u2713\nclaude -n \"feature-user-auth\" # feature work\nclaude -n \"bugfix-stripe-webhook\" # bug fix\nclaude -n \"refactor-api-routes\" # refactoring\nclaude -n \"docs-api-reference\" # documentation\nclaude -n \"review-pr-142\" # PR review\n\n# Bad names to avoid \u2717\nclaude -n \"work\" # too vague\nclaude -n \"2026-05-08\" # date alone says nothing\nclaude -n \"misc\" # meaningless\n\n# Rename an existing session from inside it\n> \/rename payment-refactor-v2\n\n# Resume later by name\nclaude --resume \"feature-user-auth\"<\/pre>\n\n\n\n\u2726<\/p>\n\n\n\n
The single most impactful habit you can build: name sessions immediately<\/strong> with -n<\/code> when you start them. “payment-integration” is findable in three months. “explain this function” is not.<\/p>\n\n\n\n09 \u00b7 Branching<\/p>\n\n\n\n
Forking sessions<\/h2>\n\n\n\n
Sometimes you want to try a different approach without losing the thread you are on. The fork<\/code> operation creates a new session that starts with a copy of the original’s history \u2014 but the original stays completely unchanged. You end up with two independent sessions you can resume separately.<\/p>\n\n\n\nSession A
original thread<\/p>\n\n\n\n
\u2192<\/p>\n\n\n\n
fork(session_A_id)<\/p>\n\n\n\n
\u2192<\/p>\n\n\n\n
Session B
new forked thread<\/p>\n\n\n\n
Both sessions share the same history up to the fork point, then diverge independently.<\/p>\n\n\n\n
typescript (SDK)<\/p>\n\n\n\n
\/\/ You analyzed an auth module in session_id.\n\/\/ Fork to explore OAuth2 without losing the JWT thread.\n\nconst forkResult = await query({\n prompt: \"Explore an OAuth2 implementation instead\",\n options: { fork: session_id }\n});\n\nconst forked_id = forkResult.session_id;\n\n\/\/ Now you have two threads:\n\/\/ session_id \u2192 JWT-focused original\n\/\/ forked_id \u2192 OAuth2 exploration\n\n\/\/ Resume the original at any time:\nawait query({\n prompt: \"Continue down the JWT path\",\n options: { resume: session_id }\n});<\/pre>\n\n\n\n\u26a0<\/p>\n\n\n\n
Forking branches conversation history, not the filesystem.<\/strong> If a forked agent edits files, those changes are real and affect the same working directory. To branch and revert file changes together, pair forking with file checkpointing.<\/p>\n\n\n\n10 \u00b7 Context management<\/p>\n\n\n\n
Managing context with \/compact<\/code><\/h2>\n\n\n\nLong sessions fill up the context window. Claude Code has a 1 million token context window, but long refactors, extensive trial-and-error, and days of continuous work can push you toward the limit. The \/compact<\/code> command summarizes the conversation history into a concise briefing and starts a fresh context window with that summary preloaded.<\/p>\n\n\n\nrepl commands<\/p>\n\n\n\n
# Check how much context you have used\n> \/status\n# \u2192 Model: claude-opus-4-6\n# \u2192 Context: 245,000 \/ 1,000,000 tokens (24.5%)\n# \u2192 Session: feature-auth-system\n\n# Compact \u2014 standard summary\n> \/compact\n\n# Compact with custom instructions\n> \/compact Keep the database design decisions but summarize the rest\n\n# Compact before switching topics to clear irrelevant history\n> \/compact Summarize the auth work so far, I'm switching to the payments module<\/pre>\n\n\n\nWith Session Memory enabled (available on Anthropic’s native API for Pro\/Max subscribers), \/compact<\/code> is instantaneous. Background summarization keeps the summary pre-written \u2014 no waiting while Claude re-reads the whole conversation.<\/p>\n\n\n\nAuto-compaction triggers automatically when you hit 95% context capacity. You can toggle this via \/config<\/code>.<\/p>\n\n\n\n\u2139<\/p>\n\n\n\n
Good time to compact: token usage exceeds 50%, you switch to a different feature, or after extensive failed attempts that can be summarized away. Compact freely \u2014 it is designed to be used often.<\/p>\n\n\n\n
11 \u00b7 Scripting<\/p>\n\n\n\n
Automation & scripting with sessions<\/h2>\n\n\n\nCapturing a session ID for later<\/h3>\n\n\n\n
Use --output-format json<\/code> to get the session ID in structured output. The session_id<\/code> field is present on every result.<\/p>\n\n\n\nbash<\/p>\n\n\n\n
# Start a session and capture its ID\nsid=$(claude -p \"Start a refactor session: list the risk points\" \\\n --output-format json | jq -r '.session_id')\n\necho \"Session ID: $sid\"\n\n# Later, resume that exact session\nclaude --resume \"$sid\" -p \"Continue with step 2 of the refactor\"<\/pre>\n\n\n\nCI\/CD pipeline integration<\/h3>\n\n\n\n
bash<\/p>\n\n\n\n
# Create a named session per build (pipeline usage)\nclaude -p \"Analyze test results and generate a bug report\" \\\n -n \"ci-test-analysis-$(date +%Y%m%d)\"\n\n# Script: run tests and check status\nclaude -c -p \"Run the tests and tell me if they pass\" \\\n --output-format json > test-results.json\n\n# One-shot query with no session saved\nclaude -p --no-session-persistence \"Explain this function briefly\"<\/pre>\n\n\n\nShell alias for quick resumption<\/h3>\n\n\n\n
bash (add to ~\/.zshrc or ~\/.bashrc)<\/p>\n\n\n\n
# Resume the most recent session for the current directory\nclaude-resume() {\n local prev_session=$(jq -r 'select(.project == env.PWD) | .sessionId' \\\n ~\/.claude\/history.jsonl | uniq | tail -2 | head -1)\n if [[ -z \"$prev_session\" ]]; then\n echo \"claude-resume: no previous session found for $PWD\"\n return 1\n fi\n echo \"Resuming session: $prev_session\"\n claude --resume \"$prev_session\"\n}<\/pre>\n\n\n\nParallel sessions with Git worktrees<\/h3>\n\n\n\n
For truly isolated parallel work \u2014 a bugfix and a new feature simultaneously \u2014 use Git worktrees to create separate working directories, then run Claude Code independently in each.<\/p>\n\n\n\n
bash<\/p>\n\n\n\n
# Create isolated worktrees\ngit worktree add ..\/project-bugfix bugfix\/stripe-webhook\ngit worktree add ..\/project-feature feature\/new-dashboard\n\n# Launch separate Claude Code sessions in each\ncd ..\/project-bugfix && claude -n \"bugfix-stripe\"\ncd ..\/project-feature && claude -n \"feature-dashboard\"\n\n# Sessions, context, and file state are fully isolated<\/pre>\n\n\n\n12 \u00b7 Recipes<\/p>\n\n\n\n
Real-world workflows<\/h2>\n\n\n\nDaily developer workflow<\/h3>\n\n\n\n
bash \u2014 a full dev day<\/p>\n\n\n\n
# Morning: list sessions and resume yesterday's work\nclaude --list\nclaude --resume \"feature-auth-system\"\n> Summarize where we left off yesterday\n\n# Late morning: focused implementation\n> Implement the backend login endpoint\n\n# Before lunch: compact to prepare for afternoon\n> \/compact Keep the implementation details and remaining tasks\n\n# Afternoon: switch to a different task\nclaude -n \"code-review-pr-142\"\n> Review PR #142 for security issues\n\n# Evening: return to the original task\nclaude --resume \"feature-auth-system\"\n> Continue from this morning \u2014 build the frontend login form<\/pre>\n\n\n\nMulti-day feature branch<\/h3>\n\n\n\n
bash \u2014 multi-day work<\/p>\n\n\n\n
# Day 1: design the data model\nclaude -n \"migration-v2\"\n> Create a migration plan for the new database schema\n\n# Day 2: continue the work\nclaude --resume \"migration-v2\"\n> Let's continue from Step 2 of the migration plan\n\n# Day 3: implementation complete, wrap up\nclaude --resume \"migration-v2\"\n> Generate the final migration scripts and test plan<\/pre>\n\n\n\nExploring alternatives without losing your place<\/h3>\n\n\n\n
typescript (SDK) \u2014 fork pattern<\/p>\n\n\n\n
\/\/ You're deep in a JWT auth implementation.\n\/\/ Want to explore Redis session storage without losing the JWT thread.\n\nconst jwtSessionId = currentSession.session_id;\n\n\/\/ Fork to explore the alternative\nconst { session_id: redisSessionId } = await query({\n prompt: \"Let's try Redis session storage instead of JWT\",\n options: { fork: jwtSessionId }\n});\n\n\/\/ ... explore Redis approach ...\n\n\/\/ Not happy? Resume the original JWT thread\nawait query({\n prompt: \"Let's stick with JWT. Continue from the token refresh logic.\",\n options: { resume: jwtSessionId }\n});<\/pre>\n\n\n\n13 \u00b7 Debugging<\/p>\n\n\n\n
Troubleshooting<\/h2>\n\n\n\n–resume returns a fresh session instead of the expected history<\/h3>\n\n\n\n
!<\/p>\n\n\n\n
Root cause:<\/strong> Mismatched working directory. Sessions are stored under ~\/.claude\/projects\/<encoded-cwd>\/<\/code>, where the encoded name is your absolute project path. If you run the resume command from a different directory (even a parent or child), Claude looks in the wrong folder and creates a new session.<\/p>\n\n\n\nFix:<\/strong> Make sure you are in the exact same directory the session was created from before running --resume<\/code>. If you need to resume across machines or directories, capture the session ID from --output-format json<\/code> and store it explicitly.<\/p>\n\n\n\n–continue creates a new session in a script<\/h3>\n\n\n\n
In non-interactive mode with -p<\/code>, --continue<\/code> may occasionally create a new session instead of resuming. This is a known limitation. For reliable automation, always use --resume<\/code> with an explicit session ID captured from the first run.<\/p>\n\n\n\nCannot find an old session<\/h3>\n\n\n\n
Use claude --list<\/code> to see all sessions. You can also inspect the global history log:<\/p>\n\n\n\nbash<\/p>\n\n\n\n
# List all sessions\nclaude --list\n\n# Search history for sessions in a specific project\njq -r 'select(.project | contains(\"my-app\")) | .sessionId + \" \" + .project' \\\n ~\/.claude\/history.jsonl | sort -u\n\n# Find sessions from a specific date\njq -r 'select(.startTime | startswith(\"2026-05\")) | .sessionId' \\\n ~\/.claude\/history.jsonl<\/pre>\n\n\n\nSession memory not available<\/h3>\n\n\n\n
Session Memory (which powers instant \/compact<\/code>) is gated behind a feature flag and requires Anthropic’s native API. It is not<\/strong> available on Bedrock, Vertex, or Foundry. If you are on a Pro or Max subscription and don’t see “Recalled\/Wrote memories” messages, your account may be in a gradual rollout queue.<\/p>\n\n\n\nPermissions asking for re-approval after resume<\/h3>\n\n\n\n
Tool permissions can expire for security reasons. Simply re-approve when prompted. For development environments where you want to skip approvals entirely, you can use --dangerously-skip-permissions<\/code> \u2014 but only in well-controlled environments like Docker containers or CI pipelines.<\/p>\n\n\n\n14 \u00b7 Best practices<\/p>\n\n\n\n
Pro tips & best practices<\/h2>\n\n\n\n
\ud83c\udff7<\/p>\n\n\n\n
Name every session<\/h4>\n\n\n\n
Always start with claude -n \"descriptive-name\"<\/code>. It’s the single highest-ROI habit in session management.<\/p>\n\n\n\n\ud83d\udd00<\/p>\n\n\n\n
Use -c daily, -r for switching<\/h4>\n\n\n\n
For single-task daily work use --continue<\/code>. Switch to --resume<\/code> only when juggling multiple active threads.<\/p>\n\n\n\n\u26a1<\/p>\n\n\n\n
Compact proactively<\/h4>\n\n\n\n
Don’t wait for 95% capacity. Run \/compact<\/code> when switching topics or after extensive exploration.<\/p>\n\n\n\n\ud83d\udd00<\/p>\n\n\n\n
Fork to explore<\/h4>\n\n\n\n
Before trying a risky alternative approach, fork. It costs nothing and preserves your current thread.<\/p>\n\n\n\n
\ud83e\udd16<\/p>\n\n\n\n
Capture IDs in scripts<\/h4>\n\n\n\n
For automation, always use --output-format json | jq -r '.session_id'<\/code> to capture IDs. Don’t rely on --continue<\/code> in CI.<\/p>\n\n\n\n\ud83c\udf32<\/p>\n\n\n\n
Git worktrees for parallel work<\/h4>\n\n\n\n
Isolate concurrent tasks with git worktree<\/code> + separate Claude sessions. Context and file state stay fully separated.<\/p>\n\n\n\n\ud83d\udccb<\/p>\n\n\n\n
Use \/resume inside sessions<\/h4>\n\n\n\n
You don’t have to exit to switch sessions. Type \/resume<\/code> mid-conversation and pick a different thread on the spot.<\/p>\n\n\n\n\ud83d\udcd6<\/p>\n\n\n\n
CLAUDE.md for persistent memory<\/h4>\n\n\n\n
Sessions hold conversation history. For persistent project knowledge (architecture, conventions), use CLAUDE.md<\/code>. It loads automatically every session.<\/p>\n\n\n\nNaming convention reference<\/h3>\n\n\n\n
bash \u2014 recommended naming patterns<\/p>\n\n\n\n
# Use a consistent prefix that describes the type of work\n\n# Feature development\nclaude -n \"feature-user-auth\"\nclaude -n \"feature-payments-v2\"\n\n# Bug fixes\nclaude -n \"bugfix-stripe-webhook\"\nclaude -n \"bugfix-race-condition\"\n\n# Refactoring\nclaude -n \"refactor-api-routes\"\nclaude -n \"refactor-db-layer\"\n\n# Documentation\nclaude -n \"docs-api-reference\"\nclaude -n \"docs-onboarding-guide\"\n\n# Code review\nclaude -n \"review-pr-142\"\nclaude -n \"review-security-audit\"\n\n# CI \/ automation\nclaude -n \"ci-test-analysis-$(date +%Y%m%d)\"<\/pre>\n\n\n\nQuick reference card<\/p>\n\n\n\n
Everything in one place<\/h2>\n\n\n\n
bash \u2014 complete cheat sheet<\/p>\n\n\n\n
\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n CLAUDE CODE SESSION MANAGEMENT \u2014 CHEAT SHEET\n\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n\n## STARTING SESSIONS\nclaude # new session (no name)\nclaude -n \"feature-auth\" # new named session\nclaude -p --no-session-persistence # one-shot, no save\n\n## RESUMING SESSIONS\nclaude -c # continue most recent\nclaude -c \"run tests\" # continue + prompt\nclaude --resume # interactive picker\nclaude -r abc123def # resume by ID\nclaude -r \"feature-auth\" # resume by name\n\n## LISTING \/ FINDING\nclaude --list # list all sessions\n\n## INSIDE A SESSION (REPL commands)\n\/resume # switch session mid-conversation\n\/rename feature-auth-v2 # rename current session\n\/compact # summarize to free context\n\/compact Keep the auth decisions # compact with instruction\n\/status # model + token usage info\n\n## AUTOMATION\nclaude -p \"prompt\" --output-format json | jq -r '.session_id'\nclaude -r \"$sid\" -p \"continue here\"\n\n## STORAGE LOCATIONS\n# Sessions: ~\/.claude\/projects\/<path-hash>\/<uuid>.jsonl\n# History: ~\/.claude\/history.jsonl\n# Memory: ~\/.claude\/CLAUDE.md (global)\n# Memory: .\/CLAUDE.md (project, auto-loaded)<\/pre>\n\n\n\n