Claude Code Session Management: Resuming Long-Running Work

Why your terminal tab shouldn't be a single point of failure

Every engineer who has adopted Claude Code eventually hits the same wall: you're three hours into a gnarly refactor, the agent has read half your codebase into context, you've course-corrected it twice, and then your laptop needs to sleep, your terminal crashes, or you simply need to switch to a meeting. Closing that window used to feel like closing a book with no bookmark. You'd either try to reconstruct the conversation from scratch or paste a rough summary and hope the model reconstructs enough of the "why" behind its own file edits.

Claude Code session management exists to remove that anxiety. Sessions are not ephemeral chat windows — they are persisted, replayable units of work, tied to a project directory, that you can resume hours or days later with the full transcript, tool calls, and file-edit history intact. Once you understand how sessions are stored and how --continue and --resume differ, you stop treating a running agent like a fragile REPL and start treating it like a long-lived collaborator you can check in on.

This matters more as tasks get bigger. A one-line bug fix doesn't need session discipline. A multi-day migration, a large test-suite rewrite, or an agent working through a 40-file refactor absolutely does. This article walks through how Claude Code actually stores sessions, the exact commands for resuming them, and the workflows that make long-running agentic work durable instead of disposable.

How Claude Code sessions are structured

Every time you start Claude Code inside a project directory, it creates or attaches to a session tied to that directory's path. Internally, each session is a JSONL transcript — a sequential log of every message, tool call, tool result, and assistant turn — stored on disk, scoped per project. That's the mechanism that makes resuming possible at all: nothing about your work lives only in volatile memory.

A few practical consequences follow from this:

• Sessions are project-scoped. Resuming from inside ~/code/api-service will show you sessions started in that directory, not sessions from an unrelated repo.
• Each session has a unique session ID (a UUID), which you can target directly if you have several candidate sessions to choose from.
• The transcript includes tool calls and their results, not just chat text — so when you resume, the agent doesn't just remember "we were editing auth.py," it remembers the actual diff it applied and the actual test output it saw.
• Sessions persist independently of whether the process is still running. You can quit your terminal entirely, come back the next morning, and resume exactly where you left off.

This is the foundation that makes the two core commands, --continue and --resume, meaningfully different tools rather than two names for the same thing.

`--continue`: picking up the most recent thread

The simplest case is: "I was just working on something in this folder, and I want to keep going." That's what claude --continue (or the shorthand claude -c) is for. It reattaches to the most recent session in the current working directory without asking you to pick anything.

cd ~/projects/api-service
claude --continue

If you just want to fire off a single follow-up instruction without dropping into interactive mode, you can pair it with a prompt and the print flag:

claude --continue --print "Now add integration tests for the new endpoint"

--continue is deliberately opinionated: it assumes you mean the last session in this directory, and it doesn't prompt you to choose. That's the right default for the common case — you stepped away for lunch, you're back, you want to keep coding. But it's also its limitation. If you've had three different sessions in the same repo this week (one debugging CI, one doing a dependency bump, one doing the actual feature work), --continue only ever gives you the most recent one. For anything more deliberate, you need --resume.

`--resume`: choosing exactly which session to reattach to

claude --resume (shorthand claude -r) is the tool for when "the most recent session" isn't necessarily "the right session." Run it bare, with no arguments, and Claude Code shows you an interactive picker listing recent sessions in the current project — typically with a timestamp, a short summary, and how many messages/turns each one contains.

claude --resume

That picker is genuinely useful when you've been context-switching across features during the same week in the same repository. You scan the list, recognize "ah, that's the one where I was untangling the webhook retry logic," and select it.

If you already know which session you want — say, you copied the session ID from a previous terminal's output or from a teammate — you can skip the picker entirely and pass the ID directly:

claude --resume 8f3a2b91-4c7d-4e2a-9f10-1d6e5c8a9b02

You can also combine --resume with --print and a fresh instruction, which is the pattern I use most for scripted or CI-adjacent workflows — reattach to a known session, hand it one more instruction, capture the output, and exit:

claude --resume 8f3a2b91-4c7d-4e2a-9f10-1d6e5c8a9b02 \
  --print "Re-run the failing test suite and summarize what changed"

The distinction to internalize: `--continue` is "keep going," `--resume` is "let me choose." Reach for --continue in the flow of ordinary daily work. Reach for --resume when you're managing multiple parallel threads of work in the same project, or when you need to hand a specific session ID to a script, a teammate, or a scheduled job.

A worked example: resuming a multi-day migration

To make this concrete, imagine you're doing a database migration — moving a service from raw SQL queries to an ORM layer. This is the kind of task that realistically spans several sessions across several days, because you're waiting on code review, running migrations against staging, and fixing edge cases as they surface.

Day one, you kick off the work:

cd ~/projects/orders-service
claude "Audit every raw SQL query in src/db/ and propose an ORM migration plan before writing any code"

The agent reads through the codebase, proposes a plan, and you approve incremental execution. A few hours in, you close your laptop. The session is safely on disk — nothing is lost.

Day two, you don't remember the exact session ID, and you only worked on one thing yesterday, so --continue is the fast path:

cd ~/projects/orders-service
claude --continue

The agent picks up with full memory of the plan it proposed, which files it had already migrated, and which tests were passing. You ask it to keep going on the next batch of queries.

Day three, though, you've also started a second, unrelated session in the same repo to fix a flaky CI job. Now --continue would grab the CI-fix session instead of the migration session, since that's more recent. This is exactly the moment to use --resume:

claude --resume

You pick the migration session from the list, and the agent resumes with the accumulated context of the whole multi-day effort — not just the last message, but the entire tool-call history of every file it touched.

Combining session flags with other Claude Code options

Session management doesn't exist in isolation — it composes with other flags you're likely already using.

Print mode for automation. If you're wiring Claude Code into a script or a pre-commit hook, --print (or -p) suppresses the interactive UI and just streams the final answer, which pairs naturally with --resume <id> for "reattach, do one thing, exit":

claude --resume "$SESSION_ID" --print "List every file changed in this session and why"

Directory targeting. Since sessions are scoped to the working directory Claude Code was launched from, if you're resuming from a script or a different shell than the one you started in, make sure you cd into the exact same project root first. Resuming from a subdirectory or a sibling directory won't find the session, because the scoping is path-based.

Permission and tool settings still apply on resume. Anything configured in your project's .claude/settings.json — allowed tools, hooks, MCP servers — is re-evaluated when a session resumes. This matters if you changed permissions between sessions: a resumed session respects your *current* settings, not whatever was in effect when the session originally started.

A minimal end-to-end pattern that's worth memorizing:

# Start work
claude "Implement rate limiting middleware for the public API"

# ...come back later, same directory, keep going
claude --continue

# ...or, if there were multiple sessions, choose explicitly
claude --resume

# ...or target a known session non-interactively for a scripted check-in
claude --resume 8f3a2b91-4c7d-4e2a-9f10-1d6e5c8a9b02 --print "Status update, one paragraph"

Practical habits for long-running agentic work

A few habits make session-based workflows much smoother in practice, especially once you're running Claude Code across several concurrent efforts:

• One directory, one line of work, when possible. Session scoping is directory-based, so if you run two unrelated efforts in the same repo root at the same time, --continue becomes ambiguous in spirit even though it's mechanically deterministic (it just grabs the latest). Using git worktrees or separate clones for genuinely parallel efforts keeps --continue meaningful.
• Ask the agent to summarize before you step away. At a natural stopping point, a quick "summarize what's done, what's left, and any open questions" turns the transcript into a readable checkpoint — useful both for your own memory and for a teammate who might resume the session instead of you.
• Note session IDs for anything you'll hand off. If you're pausing work that a teammate or a CI job will resume later, copy the session ID out of the terminal output before you close it. --resume with an explicit ID is far more reliable in a handoff than hoping the picker surfaces the right one later.
• Don't let sessions become a substitute for commits. Session persistence protects your *conversation and reasoning* history, not your git history. Commit working states as you go — the agent's transcript memory and your version control history should reinforce each other, not replace one another.
• Use `--print` for anything you're scripting. Interactive mode is for you at the keyboard; print mode is for anything unattended — a nightly check, a CI step, a cron-triggered nudge to an agent that's mid-task.

The underlying idea across all of these habits is the same one that makes session management worth learning in the first place: a Claude Code session is a durable artifact, not a throwaway chat. Treat it the way you'd treat a branch — something you can leave, return to, hand off, and inspect — rather than something you have to finish in one sitting or lose.

Where this fits in the bigger picture

Session management is a small feature surface — really just two flags and a picker — but it changes how you're willing to structure work. Once you trust that closing your laptop doesn't cost you three hours of accumulated context, you start giving Claude Code bigger, multi-day tasks instead of chopping everything into single-sitting chunks. That shift, from "quick single-shot prompts" to "an agent that works alongside you across a real engineering timeline," is where a lot of the practical value of agentic coding tools actually shows up.

If you're building the muscle memory for this kind of workflow — not just session flags, but the broader discipline of directing an AI coding agent through real projects, debugging its output, and structuring multi-step tasks so they survive interruptions — that's exactly the ground we cover in the Claude Code Tutorial for Beginners course on teachyou.ai. It walks through the CLI from first principles up through the workflows professional engineering teams actually rely on day to day.