Original URL: https://getagenttools.com/blog/claude-resume/

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

18 Sep 2026Marek.

- claude-code
- agent-ops
- context-engineering

`claude --resume` is the [Claude Code](https://getagenttools.com/tools/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](https://getagenttools.com/blog/claude-code-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](https://code.claude.com/docs/en/sessions) 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:

 

| Command | What it does |
| --- | --- |
| `claude --continue` | Reopens the latest conversation in the current directory |
| `claude --resume` | Opens the session picker |
| `claude --resume <name>` | Resumes the named session directly |
| `claude --resume <transcript-path>` | Loads the `.jsonl` transcript at that absolute path |
| `claude --from-pr <number>` | Opens the picker filtered to sessions linked to that pull request |
| `/resume` | Switches to another conversation from inside a running session |

 

The short forms are `-c` and `-r`; the example in the [CLI reference](https://code.claude.com/docs/en/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](https://getagenttools.com/blog/claude-code-worktrees/), including its branch, working directory and uncommitted changes.

 

| State | After a terminal resume |
| --- | --- |
| Conversation history | Restored in full, tool calls and results included |
| A tool still running when the process ended | Not finished, not run again; Claude continues without its output |
| Model | Restored, unless it was retired, is blocked by `availableModels`, or `--model` or an `ANTHROPIC_MODEL` variable picks one at launch |
| Agent from `--agent` or the `agent` setting | Restored with its tool restrictions and model; default tools plus a warning if the agent file is gone |
| Permission mode | Restored when you resume by ID, by an unambiguous name or with `--continue`, without `-p` |
| Permission mode via the picker or `/resume` | Not restored; the session takes the mode a new one would get, or the mode you are already in |
| `bypassPermissions` | Not restored on any path; enable it again at launch or in `permissions.defaultMode` |
| `plan` | Not restored on a terminal resume; restored under `-p` and in VS Code under conditions, from v2.1.246 |
| Active goal | Carries over; its turn count, timer and token baseline reset |
| Scheduled tasks | Restored if they have not expired |
| Background Bash and monitor tasks | Not restored |
| `--mcp-config`, `--settings`, `--plugin-dir`, `--fallback-model`, `--add-dir`, mid-session `/add-dir` | Not restored; pass them again |
| `settings.json` and `settings.local.json` | Re-read at launch; nothing to pass |

 

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](https://getagenttools.com/blog/claude-code-checkpoints/), 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](https://getagenttools.com/blog/claude-code-context-window/) 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:

 

```bash
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](https://getagenttools.com/blog/claude-code-subagents/) 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](https://getagenttools.com/blog/claude-code-memory/); 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](https://learn.chatgpt.com/codex/developer-commands) 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](https://learn.chatgpt.com/docs/projects), and the [command line options page](https://learn.chatgpt.com/docs/cli/reference) 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](https://opencode.ai/docs/cli/) lists `--continue` or `-c` to "Continue the last session", `--session` or `-s` for an ID, and `--fork`. In the TUI, per the [TUI page](https://opencode.ai/docs/tui/), `/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](https://cursor.com/docs/cli/reference/parameters) 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](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli): "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](https://code.claude.com/docs/en/sessions), [CLI reference](https://code.claude.com/docs/en/cli-reference), [Commands](https://code.claude.com/docs/en/commands) and [Context window](https://code.claude.com/docs/en/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.

Put this into practice

[See the tool list](https://getagenttools.com/tools/)[Train your team](https://getagenttools.com/#training)