What you will be able to do
- Choose between continue, resume and a new session for a given workflow
- Name a Claude Code session and resume it with --resume <session-name> on a later day
- Capture a session ID in the Agent SDK and pass it to resume
- Explain what a resumed session restores and why the session file must be on the current machine
- Decide between resuming a session whose prior context is mostly valid and starting fresh with an injected summary when prior tool results are stale
- Tell a resumed session which files changed so it re-analyzes those files instead of re-exploring the whole codebase
Key concept
Session — A session is the saved conversation history of an agent run, written to disk so you can return to it later. Continuing or resuming adds to that same history. Forking copies it into a new, independent history.
1.Continue, resume, or start new
Every agent run leaves a saved conversation behind. The first design question is how you get back to it. The Agent SDK documentation answers this with a decision table, and its main distinction is between *continue* and *resume*. Continue needs no bookkeeping. It picks up the most recent session in the current directory, which suits an app that runs one conversation at a time. Resume targets one particular session by its ID. You need it when several sessions exist side by side, for example one per user, or when the session you want is not the latest one.
| What you're building | What to use |
|---|---|
| One-shot task, no follow-up | Nothing extra; one query() call |
| Multi-turn chat in one process | ClaudeSDKClient (Python) or continue: true (TypeScript) |
| Pick up after a process restart | continue_conversation=True (Python) / continue: true (TypeScript), which takes the most recent session in the directory |
| Return to a specific past session that is not the most recent | Capture the session ID and pass it to resume |
| Try an alternative approach without losing the original | Fork the session |
The same split exists in the Claude Code CLI. claude --continue reopens the most recent conversation in the current directory. To continue a specific prior conversation instead, use named session resumption: give the session a name, then run claude --resume <session-name> to go straight back to that conversation, even when other sessions have run since. A name is the CLI's equivalent of the session ID you track in the SDK. It is the handle for a particular conversation, so you don't have to rely on that conversation still being the latest. If you pick up the same investigation across several work sessions, name it and resume it by that name. Use --continue only when the conversation you want is the latest one.
Checkpoint 1 of 7· Check yourself
A multi-user app keeps one agent conversation per customer. A customer comes back the next day, and their conversation is not the most recent one in the directory. What should the app use?
Continue always takes the most recent session in the directory. To reach one particular session among many, you need its ID, passed to resume.
“Resume takes a specific session ID. You track the ID.”Source: code.claude.com
2.Named sessions in Claude Code: --resume <session-name>
An investigation often runs across several work sessions: you dig into the auth module on Monday and come back on Wednesday. Tracking session IDs by hand gets in the way. Claude Code lets you give the session a name instead. You can set the name at startup with claude -n auth-refactor. During the session you can run /rename auth-refactor, and in the session picker you can highlight a session and press Ctrl+R. Later, claude --resume auth-refactor takes you straight back. The short form also accepts a prompt, so claude -r "auth-refactor" "Finish this PR" resumes the session and gives it the next instruction in one command.
Not every label works as a handle. If you leave a session unnamed, Claude Code gives it a default display name (the directory name plus a two-character suffix) that shows up in running-session listings. That name can't be passed to --resume. The *generated title*, a short summary of your first prompt, does work, and so does a title produced when you accept a plan. Matching also behaves differently depending on where you resume from. If a name matches exactly, both claude --resume <name> and /resume <name> go straight to the session. If the name is ambiguous, claude --resume opens the picker with the name filled in as a search term, while /resume <name> inside a session reports an error.
Checkpoint 2 of 7· Match them up
Match each command to what it does
Tap a term, then the definition that fits it.
Naming happens at startup or during the session. --resume <name> jumps to a session by name, and --continue only ever opens the latest one.
“Resumes the named session directly”Source: code.claude.com
3.Resuming by ID in the Agent SDK
In the SDK, the handle is the session ID, and you read it from the result message at the end of a run. The documentation gives three reasons to resume. One is following up on a finished analysis without having the agent read the files again. Another is retrying after a run hit error_max_turns or error_max_budget_usd, this time with a higher limit. The third is restoring a conversation after your process restarts.
if isinstance(message, ResultMessage):
session_id = message.session_id # Earlier session analyzed the code; now build on that analysis
async for message in query(
prompt="Now implement the refactoring you suggested",
options=ClaudeAgentOptions(
resume=session_id,
allowed_tools=["Read", "Edit", "Write", "Glob", "Grep"],
),
):The tool list changed between the two runs. The analysis run used read-only tools, and the resumed run adds Edit and Write. Options are set for each call, so resuming doesn't lock you into the original run's configuration.
Checkpoint 3 of 7· Put it in order
Put the steps for returning to a specific SDK session in order
- 1.Read session_id from the ResultMessage and store it
- 2.Run the first query() with read-only tools to analyze the code
- 3.Start a new query() with resume set to the stored ID and a follow-up prompt
You can only resume an ID you captured earlier, and that ID comes from the first run's result message.
“Capture the session ID and pass it to resume.”Source: code.claude.com
Sources1
4.What resuming restores, and where the session file must be
In Claude Code, resuming brings back more than the messages. The full conversation history returns, including tool calls and their results. The session normally stays on the same model and the same --agent. When you resume from a terminal with a name or ID, Claude Code usually restores the permission mode too. Some things don't come back: background Bash and monitor tasks aren't restored. If a tool was still running when the earlier process ended, Claude sees that call marked as cut off and is told to check whether it took effect before running it again.
Sessions are local files. The SDK stores each transcript at ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl, and resume only works if that file is on the machine doing the resuming. Ephemeral CI workers trip over this: an ID created on one build machine means nothing on another. There are three fixes. You can attach a session store so transcripts are mirrored to your own backend. You can copy the .jsonl file into ~/.claude/projects/ on the new host. Or you can skip resume entirely and pass the results you captured into a fresh session's prompt.
Checkpoint 4 of 7· Exam question
While a session is resumed via --continue --fork-session to try a riskier approach, the architect notices that a permission the original session had approved with 'allow for this session' is being re-prompted in the new branch. Why does this happen?
Correct answer: A — Session-scoped permission approvals do not carry over from the original session into a newly forked branch
- A. Correct. Documented forking behavior states that permissions approved with 'allow for this session' do not carry over to the new branch, so the branch re-prompts even though the conversation history is copied.
- B. Incorrect: --fork-session combines validly with either --continue or --resume; the flag pairing is not the cause of the re-prompt.
- C. Incorrect: forking branches conversation history, not the working directory, and the directory itself is unaffected by the fork.
- D. Incorrect: permission approvals are not turn-limited; they are simply scoped to the session in which they were granted and do not propagate to new branches.
Checkpoint 5 of 7· Check yourself
Your SDK app runs on several hosts behind a load balancer, and any host may get a user's next request. Which approach lets any host resume that user's session?
An ID alone fails on a host that doesn't have the transcript file. A session store mirrors transcripts so another host can load them. persistSession: false is the reverse, because nothing gets written at all.
“Attach a sessionStore / session_store adapter so the SDK mirrors transcripts to your own backend and another host can resume them.”Source: code.claude.com
5.Resume, or start fresh with an injected summary
Resuming brings back the full history, including every tool call and tool result from the earlier run. That is what makes it valuable: when the agent has already analyzed something, it can act on that analysis without reading the files again. It is also the risk. Those tool results are a record of the files *as they were when the agent read them*. If the code has changed a lot since then, the resumed session starts from a picture of the codebase that is no longer accurate.
So the choice between session resumption and starting fresh depends on how much of the prior context is still valid. Resume when the prior context is mostly valid: the files the agent read are largely unchanged, and you want to build on its analysis. Start a new session with an injected summary when the prior tool results are stale. Capture what is worth keeping (the analysis output, the decisions made, the file diffs) as application state, and put that structured summary in the fresh session's first prompt. The documentation calls this approach often more robust than moving transcript files around. A fresh session also avoids carrying a long history full of outdated tool output. As a context window grows, the model recalls information from it less accurately, so a short, current summary is a better starting point than a large, stale transcript.
Checkpoint 6 of 7· Check yourself
Yesterday an agent session analyzed your payments module. Overnight, a teammate rewrote most of the files it read. You want the agent to propose the next refactoring step. Which approach is more reliable?
The resumed history would contain tool results for files that no longer look that way. Carrying the conclusions forward as application state into a fresh session's prompt keeps what is still useful and drops the stale reads.
“Capture the results you need (analysis output, decisions, file diffs) as application state and pass them into a fresh session’s prompt.”Source: code.claude.com
6.Telling a resumed session what changed
Sometimes resuming is still the right call after code modifications. Most of the earlier analysis may still hold, and only a few files changed. In that case the resumed session needs to be told about the changes. It has no way of noticing that a file it already analyzed was edited after it read it, or that a new file appeared. Anthropic's scheduled repository reviewer cookbook shows this risk. Between two review runs, one bug is fixed and a new file, app/retry.py, is added. The cookbook notes that without an explicit instruction in the follow-up prompt, the resumed agent can answer from the files it read in the first run and never notice the new file. Its fix is to make the follow-up prompt's first instruction a fresh listing of the repository's files.
The general lesson is that the prompt you send on resume is your only way to tell the agent what changed. If you know which files changed, name them. For example: "Since your last review, app/math_utils.py was edited to add a zero guard and app/retry.py is new. Re-read those two files and update your findings." The agent then re-analyzes only the files that changed and keeps the rest of its earlier analysis. That is the point of resuming instead of starting over: it avoids a full re-exploration of the codebase. If the changes are too widespread to list, that is a sign the prior context is mostly stale, and starting fresh with a summary is the better choice.
Checkpoint 7 of 7· Check yourself
You resume a code-review session after fixing one file it flagged and adding a new module. Most of its earlier analysis still applies. What should the resume prompt do?
A resumed agent keeps working from the file contents it already read, so on its own it can miss both the edit and the new file. Naming the changed files gets a targeted re-analysis and keeps the analysis that is still valid.
“Without that step, a resumed agent can answer from the files it read in run 1 and never notice that app/retry.py is new.”Source: platform.claude.com
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.The default display name shown for an unnamed session (such as my-app-3f) can be passed to --resume.Why is that wrong?
The default display name only labels running sessions in listings. You can resume by a name you set or by a generated title, but not by the default display name.
Covered in Named sessions in Claude Code: --resume <session-name>
2.With an ambiguous name, /resume <name> behaves the same as claude --resume <name> and opens the picker.Why is that wrong?
claude --resume opens the picker with the name pre-filled. /resume <name> inside a session reports an error instead.
Covered in Named sessions in Claude Code: --resume <session-name>
3.A session ID is enough to resume the conversation from any machine.Why is that wrong?
Resume reads a local transcript file. Without a session store or a copied file, a different host can't find the session.
Covered in What resuming restores, and where the session file must be
4.Resuming is always better than starting a new session, because the resumed session keeps everything it learned.Why is that wrong?
When the files have changed, the resumed history carries stale tool results. Passing the captured conclusions into a fresh session's prompt is often more robust.
5.A resumed session automatically notices files that changed or were added since it last read them.Why is that wrong?
The resumed agent can keep working from the file contents it already read. You have to tell it what changed, or tell it to look again.
Covered in Telling a resumed session what changed
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://code.claude.com/docs/en/agent-sdk/sessionsOfficial docs
“Continue finds the most recent session in the current directory.”
↩︎ Continue, resume, or start new“The agent already analyzed something; now you want it to act on that analysis without re-reading files.”
↩︎ Resuming by ID in the Agent SDK“Same machine only: the session file still needs to exist on the current machine.”
↩︎ What resuming restores, and where the session file must be“Capture the results you need (analysis output, decisions, file diffs) as application state and pass them into a fresh session’s prompt.”
↩︎ Resume, or start fresh with an injected summary“The agent already analyzed something; now you want it to act on that analysis without re-reading files.”
↩︎ Resume, or start fresh with an injected summary“now you want it to act on that analysis without re-reading files.”
↩︎ Telling a resumed session what changed“How sessions persist agent conversation history, and when to use continue, resume, and fork to return to a prior run.”
↩︎ Key concept“Same machine only: the session file still needs to exist on the current machine.”
↩︎ Exam trap 3“This is often more robust than shipping transcript files around.”
↩︎ Exam trap 4“Resume takes a specific session ID. You track the ID.”
↩︎ Checkpoint“Capture the session ID and pass it to resume.”
↩︎ Checkpoint“Attach a sessionStore / session_store adapter so the SDK mirrors transcripts to your own backend and another host can resume them.”
↩︎ Checkpoint - 2.https://code.claude.com/docs/en/sessionsOfficial docs
“Resumes the named session directly”
↩︎ Continue, resume, or start new“Reopens the most recent conversation in the current directory”
↩︎ Continue, resume, or start new“Opens the session picker with the name pre-filled as a search term”
↩︎ Named sessions in Claude Code: --resume <session-name>“You can pass either title to claude --resume or /resume, and Claude Code resolves it the same way as a name you set.”
↩︎ Named sessions in Claude Code: --resume <session-name>“the full history, including tool calls and results”
↩︎ What resuming restores, and where the session file must be“Conversation history: the full history, including tool calls and results.”
↩︎ Resume, or start fresh with an injected summary“The default isn’t a resume handle.”
↩︎ Exam trap 1“Reports an error; run /resume with no argument to open the session picker”
↩︎ Exam trap 2“The default isn’t a resume handle.”
↩︎ Prediction“Resumes the named session directly”
↩︎ Checkpoint - 3.https://code.claude.com/docs/en/cli-referenceOfficial docs
“Resume session by ID or name”
↩︎ Named sessions in Claude Code: --resume <session-name> - 4.
“as the number of tokens in the context window increases, the model’s ability to accurately recall information from that context decreases.”
↩︎ Resume, or start fresh with an injected summary - 5.https://platform.claude.com/cookbook/claude-agent-sdk-scheduled-repository-reviewer-scheduled-repository-reviewerSecondary source
“Without that step, a resumed agent can answer from the files it read in run 1 and never notice that app/retry.py is new.”
↩︎ Telling a resumed session what changed“The prompt's first instruction is to list the repository's files again.”
↩︎ Telling a resumed session what changed“Without that step, a resumed agent can answer from the files it read in run 1 and never notice that app/retry.py is new.”
↩︎ Exam trap 5