Skip to main content
A session is a saved conversation tied to a project directory. Claude Code stores it locally as you work, so you can resume where you left off, branch to try a different approach, or switch between tasks. The desktop app, Claude Code on the web, and the VS Code extension each maintain their own session history. This page covers the CLI.

​
Resume a session

Sessions are saved continuously to local transcript files as you work, so you can return to one after exiting or running /clear. Use these entry points: Sessions created with claude -p or the Agent SDK don’t appear in the session picker, but you can still resume one by passing its session ID to claude --resume <session-id>. You can run claude --resume <session-id> from any directory: Claude Code looks for the ID in the current project directory and its git worktrees first, then in every other project on this machine, so it finds a session that started elsewhere or moved with /cd. The cross-project search resolves the ID only when exactly one other project holds a transcript with messages for it, so a hand-copied duplicate makes Claude Code report not-found rather than resume an arbitrary copy. If no stored session matches the ID, Claude Code reports No conversation found with session ID: <session-id>. 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.

​
What a resumed session restores

A resumed session restores the conversation along with the state saved in it:
  • Conversation history: the full history, including tool calls and results.
  • Model: the session continues on the model it was using. The model isn’t restored when it has been retired or isn’t allowed by availableModels, when a --model flag or ANTHROPIC_MODEL-family environment variable picks one at launch, or on providers that use provider-specific deployment IDs, such as Amazon Bedrock, Google Cloud’s Agent Platform, and Microsoft Foundry; see model configuration for the resolution order.
  • Agent: a session started with --agent or the agent setting continues as that agent, keeping its system prompt, tool restrictions, and model. Pass --agent when resuming to pick a different one. Claude Code looks for the agent in two places: the session’s original directory, provided you have trusted that workspace, and then the directory you resume from, so a project-scoped agent still loads when you resume from another directory. If Claude Code doesn’t find the agent in either place, the session resumes with the default tools and system prompt and shows a warning naming the agent.
  • Permission mode: the mode the session was in, with these exceptions. Pass --permission-mode to override the restored mode.
    • plan and bypassPermissions are never restored; a session that was in one of them resumes in the mode a new session would start in. To bypass permissions again, enable it at launch with one of its launch flags or permissions.defaultMode: "bypassPermissions" in settings
    • auto is restored only when your account still meets the auto mode requirements
    • Manual is restored as Manual when a new session would start in auto mode from the built-in default; when a defaultMode from a settings file takes effect, the session resumes in that mode instead
  • Active goal: a goal that was still active when the session ended carries over; its turn count, timer, and token-spend baseline reset.
  • Scheduled tasks: tasks that haven’t expired are restored. Background Bash and monitor tasks aren’t.
Not every configuration flag from the original launch is restored. If the session depended on --mcp-config, --settings, --plugin-dir, --fallback-model, or directories added with --add-dir, pass them again when you resume; directories added mid-session with /add-dir aren’t restored either, though the session picker still uses them to locate the session. The standard settings files, such as settings.json and settings.local.json, are re-read at launch, so configuration that lives in them doesn’t need to be passed again.

​