claude --resume: what a resumed session restores, what it drops, and what my cheat sheet got wrong

claude --resume is the Claude Code flag that reopens a saved session from the transcript on your disk, with the whole conversation, tool calls and tool results included. If you typed this string looking for a résumé, this page is about the CLI flag, not the document. On the morning of 15 September 2026 the transcript folder of one of my projects held 215 .jsonl files, a month of sessions at the default retention, and most of my working days start by reopening one of them. This post is the docs' sessions page read against that folder, plus the cheat sheet line that turned out to be a version behind.

• What it is. One of six entry points into a saved session. --continue reopens the latest conversation in the current directory, --resume opens a picker or takes an ID, a name or a transcript path, --from-pr filters by pull request, and /resume switches conversations from inside a session.
• What comes back. The full history with tool results, the model, the agent, the permission mode in most terminal cases, the active goal and any scheduled task that has not expired.
• What does not. A tool that was mid-run when the process died, background Bash and monitor tasks, bypassPermissions, and launch flags such as --mcp-config, --settings, --plugin-dir and --add-dir.
• What it costs. A resume loads the full history back into the context window. Past 100,000 tokens and about an hour of silence, Pro and Max plans get a dialog offering a summary.
• What my cheat sheet got wrong. It said to resume from the same directory. Since v2.1.223 a session ID resolves from any directory on the machine.

How do I resume Claude?

Run claude --continue to reopen the latest conversation in the current directory, or claude --resume to pick one from a list. claude --resume <session-id> or claude --resume <name> goes straight to a specific session, and /resume switches conversations without leaving the terminal. Sessions save continuously, so nothing needs to be exported first.

The docs' definition on the Manage sessions page is one sentence: "A session is a saved conversation tied to a project directory." Claude Code writes the transcript as you work, so the session you closed with Ctrl+C or lost to a crash is already on disk at ~/.claude/projects/<project>/<session-id>.jsonl. That is the folder I counted: 215 files on the morning of 15 September 2026, under the default 30-day retention (cleanupPeriodDays changes it), which works out to about seven sessions a day in one project. What the folder cannot tell you is how often I resumed: the shell command that opens a session is typed before the session exists and never lands in the transcript, so a grep for claude --resume counts mentions in messages and tool output, not uses.

claude --resume previous session: the six entry points

The sessions page lists six ways in. Condensed from its table:

The short forms are -c and -r; the example in the CLI reference is claude -r "auth-refactor" "Finish this PR", a resume by name with the prompt attached. Two groups stay out of the picker and out of --continue: runs started by claude -p or the SDK, and any session that opened with /loop. The first group still opens by ID with claude --resume <session-id>. For the second, the docs say only that with claude -p --continue, "Claude Code includes -p, SDK, and /loop sessions".

The picker is where most of my resumes start. Typing filters, Space previews, Ctrl+R renames, Ctrl+A widens to every project on the machine, Ctrl+W to every worktree, Ctrl+B narrows to the current branch. The file size on each row predicts the dialog described below.

Names are the cheaper habit. claude -n auth-refactor at launch or /rename mid-session gives a session a handle for claude --resume <name>; a name a live session already uses gets a suffix such as auth-refactor-graceful-unicorn. The default display name, something like my-app-3f, is not a resume handle; the generated title from your first prompt is.

claude --resume with a session id from any directory

My cheat sheet, translated: --continue for the last conversation, --resume <session_id> from the same directory. The docs today say the opposite. claude --resume <session-id> works from any directory: Claude Code looks in the current project and its git worktrees first, then in every other project on the machine, and resolves across projects only when exactly one of them holds a transcript with messages for that ID. A wrong ID gets No conversation found with session ID: <session-id>.

The page dates the change: "Before v2.1.223, the lookup stopped at the current project directory and its git worktrees, so you had to resume from the directory the session last worked in." My sheet was right when I wrote it and wrong by the time I quoted it: a cheat sheet line without a version number is a docs sentence frozen at an unknown date. Two things did not move the same way. Names have a narrower reach: "Resuming by name resolves across the current repository and its worktrees." And the picker still opens on the current worktree and needs Ctrl+A to widen. So "any directory" holds for an ID; a name resolves across the current repository and its worktrees, and the list needs Ctrl+A.

Claude Code resume last session: --continue and what it skips

claude --continue reopens the latest conversation in this directory and nothing else. It skips claude -p and SDK runs, sessions that opened with /loop, and a background session still running; a finished background session opens from v2.1.257. If your latest conversation is still running in the background, the command exits with Your most recent conversation is running in the background.

--continue is the flag I reach for least, and that comes from the setup, not from taste. Several sessions run on the same repository at once here, so "latest" means whichever terminal wrote last, rarely the one I want, and I paste the ID from the handoff note instead.

What a resumed session restores and what it drops

The table condenses the docs' section "What a resumed session restores" and its permission-mode subsection; every row is from the docs, none from my transcripts.

Before continuing file edits, check the worktree before resuming edits, including its branch, working directory and uncommitted changes.

Two rows carry most of the surprises: a session that ran under --dangerously-skip-permissions comes back asking again, whichever way you resume it, and a session that depended on --mcp-config resumes without those servers unless you repeat the flag. One rule from the branching section: resume the same session in two terminals without forking and "messages from both interleave into one transcript". For a second copy, --fork-session gives the resume a new ID and /branch does it from inside.

If the next step is to rewind tracked edits after resuming, check the checkpoint scope before choosing code, conversation or both.

Resume from a summary: the dialog on big sessions

On a Pro or Max plan, resuming a session idle for more than about an hour and over 100,000 tokens opens a dialog before your first message. The prompt cache has expired by then, so the next request processes the full history once whatever you choose.

• Resume from summary runs /compact immediately: a summary, your most recent exchanges and up to five recently read files.
• Resume full session as-is loads the conversation unchanged.
• Don't ask me again resumes in full and retires the dialog.

I take the summary on almost every session that qualifies: a session heavy enough for the dialog was heavy when I left it, and usually that is why I left. What survives the summary is a fixed list; the context window post walks through it.

When I resume, when I /clear, when I hand off

The docs give the commands; the thresholds are my practice. /clear starts an empty context and keeps the old conversation resumable through /resume, and /clear <name> labels the conversation you are leaving. /compact [instructions] replaces history with a focused summary; /context shows what fills the window now.

• Same task, same day, window well under the dialog threshold. claude --resume with the ID. The common case.
• Same task, next day, or a window that would trigger the dialog. A handoff: a new session on a short note naming the files touched, the decisions made and the next step, plus the old session ID. My operating rules say it plainly: a long session dulls the model. The docs' script example is the handoff generator I used to write by hand:

claude -p --resume <session-id> --output-format json "summarize what we changed" | jq -r '.result'

• Different task. /clear release-prep, naming what I leave, so the picker shows a label instead of a first prompt.
• A large read mid-task. Neither. A subagent reads in its own window and returns a summary; the main session never carries the file.
• One task that must stay in one window and is getting heavy. /compact with a focus instruction before the next big step.

Rules that live only in the conversation survive neither the summary nor the handoff. Anything every session must know goes into the file described in the Claude Code memory post; the resume carries the work, not the rules.

The Read-before-Edit rule after a resume

The edit tool needs a read of the file inside the current context window, or it refuses. My project CLAUDE.md asks for a fresh read, a fragment is enough, in three cases: after compaction, on returning to a file edited earlier in the session, and after a "modified since read" error. The rule exists because between 9 and 16 July 2026 I counted 33 refused edit calls. Codex CLI fails the same way with apply_patch verification failed: same root cause, same fix.

A resume adds a fourth case. The history comes back with the old reads in it, but the summary path runs /compact, which brings back at most five files and turns any file over 5,000 tokens into a path reference without content, per the context window docs. On a shared repository the file may also have changed on disk while the session was closed. So after any resume I treat every file as unread; a redundant read costs a few hundred tokens, the refused edits cost 33 calls in a week.

Resume in Codex, opencode, Cursor and Copilot CLI

Everything below is from the vendors' docs read on 15 September 2026, and only what the pages said.

Codex CLI has a subcommand, not a flag. The developer commands page lists codex resume as stable: "Continue an interactive session by ID or resume the most recent chat." --last skips the picker and takes the most recent chat from the current working directory, --all includes other directories. Inside a chat, /resume does the same job, per the projects and chats page, and the command line options page has no flag spelled --resume. That page adds the behaviour Claude Code handles differently: "If the current working directory differs from the session's saved directory, Codex asks which directory to use." Claude Code searches and decides; Codex asks. One URL from my notes, learn.chatgpt.com/docs/cli-reference, returned 404.

opencode mirrors the Claude Code pair. The CLI page lists --continue or -c to "Continue the last session", --session or -s for an ID, and --fork. In the TUI, per the TUI page, /sessions lists and switches, with /resume and /continue as aliases and ctrl+x l as the key; /new, alias /clear, starts over.

Cursor CLI uses the same words with a twist. The parameters reference has --resume [chatId] and --continue, defined as an alias for --resume=-1, plus agent resume for the latest chat. The page also lists agent ls, described there as "Resume a chat session", which I read as the picker. The editor's chat history was not checked.

GitHub Copilot CLI documents both routes on its how-to page: "You can use the --resume command-line option or the /resume slash command to select and resume an interactive CLI session...", and copilot --continue for the most recently closed local session.

Gemini CLI: not checked.

The verdict

RUNNING. This is not a feature I tested once; it is how the terminal opens on most working days. What the docs changed in my routine: the cheat sheet line gets a version number, every handoff note carries the session ID, the summary is the default on a heavy session, and a resume counts as an unread window for the edit tool.

Sources: the Claude Code docs pages Manage sessions, CLI reference, Commands and Context window, read on 15 September 2026 and the source of every quote, version number and table row above; the vendor pages linked in the cross-agent section, read the same day; and the transcript count, cheat sheet line and edit-call figure from my own machine and notes.