Managing Claude Code sessions: the built-in session manager and when you need more

Claude Code already has a session manager built in. claude --resume opens a picker of saved conversations that you can search, rename, preview and widen to every project on your machine, and claude agents opens agent view, a live list of background sessions showing which are working, which need you and which are done. The desktop app adds a sidebar with the same job. A third-party manager is worth adding only for something these do not do, such as one view across Claude Code and other agents like Codex.

What Claude Code counts as a session

A session is a saved conversation tied to the directory you started it in. Claude Code writes it to disk continuously, as a JSONL transcript at ~/.claude/projects/<project>/<session-id>.jsonl, where <project> is the working directory path with non-alphanumeric characters replaced by hyphens. That is why you can come back to a conversation after exiting or running /clear.

Two details explain most "where did my session go" questions. First, the terminal CLI, the desktop app, claude.ai/code and the VS Code extension each keep their own session list, so look for a conversation in the one where you started it. Second, CLI transcripts are deleted after 30 days by default, covered under retention below.

Resume and switch from the terminal

These are the entry points, all in the CLI:

A resumed session brings back the full conversation and the model it was using. It does not bring back every launch flag: if the session depended on --mcp-config, --settings, --plugin-dir, --fallback-model or directories added with --add-dir, pass them again. Directories added mid-session with /add-dir are not restored either. Configuration in settings.json files is re-read at launch, so it needs nothing extra.

The session picker searches across worktrees and projects

By default the picker lists sessions from the current worktree, including background sessions, which are marked bg. Each row shows the session's name or generated title, time since last activity, git branch and file size. The keys that make it a manager rather than a list:

• Ctrl+W widens to all worktrees of the repository, and Ctrl+A to every project on the machine. Press again to narrow back.
• Ctrl+B filters to sessions from the current git branch.
• Typing / or most other characters starts a search. Pasting a GitHub, GitLab or Bitbucket pull request URL finds the session that created it.
• Space previews a session's content and Ctrl+R renames it.

Choosing a session from another worktree of the same repository resumes it in place. Choosing one from an unrelated project copies a cd and resume command to your clipboard instead, so you run it from the right directory.

Some sessions never appear here. Runs started with claude -p or the Agent SDK, and sessions whose first prompt was /loop, are left out of the picker and out of claude --continue. You can still resume a -p or SDK session by passing its session ID to claude --resume, and claude -p --continue includes all three kinds.

Name sessions so you can find them again

An unnamed session gets a title generated from your first prompt, which is often too vague to pick out of a list of twenty. Name sessions when you run several at once:

claude -n auth-refactor

Inside a session, /rename auth-refactor sets or changes the name and shows it on the prompt bar; in the picker, Ctrl+R renames the highlighted row. You can then return with claude --resume auth-refactor from any worktree of the repository. The short label agent view shows for an unnamed session, such as my-app-3f, is a display name only: passing it to --resume finds nothing.

Branch a session instead of reusing it

To try a different approach without losing the current one, run /branch with an optional name inside the session. It copies the conversation so far into a new session and switches you into it, leaving the original unchanged in the picker. From the shell, add --fork-session to a resume:

claude --resume auth-refactor --fork-session

Do not open the same session in two terminals without forking. Messages from both interleave into one transcript.

Agent view manages the sessions that are running now

The picker is for saved conversations. For sessions that are working right now, Claude Code has agent view, a research preview. Start work in the background and open the list:

claude --bg --name flaky "find out why the settings test fails intermittently"
claude agents

Agent view lists every background session you have started, across all your projects, grouped so the ones needing you sit at the top. Each row shows a state (working, needs input, idle, completed, failed or stopped) and a one-line summary of what the session is doing or asking. Sessions open in other terminals appear once you background them with /bg, or by pressing ← on an empty prompt.

• Space peeks at a session's latest output or question and lets you reply in place; Enter attaches to the full conversation.
• Ctrl+S groups by directory instead of state, Ctrl+T pins a session, and Ctrl+R renames one.
• Typing s:blocked in the input shows everything waiting on you; n:login matches names and first prompts.
• claude agents --cwd ~/projects/my-app limits the list to one project.

The same sessions can be managed from the shell with claude attach, claude logs, claude stop and claude rm, each taking the session's short ID. For a status bar or script, claude agents --json --all lists sessions as JSON: background sessions carry a state, live processes a status, and a waiting session a waitingFor field that tells a permission prompt from a question.

The desktop app is the official GUI

If "session manager GUI" is what you searched for, the Claude desktop app's Code tab is the first-party answer. + New session (Cmd+N on macOS) starts a parallel session, the sidebar filters sessions by status, project or environment and can group them by project, and Cmd-clicking a second session opens it in a split pane. Hovering a session and clicking the archive icon removes its worktree when you are done.

Its list is separate from the CLI's. To move a terminal conversation into it, run /desktop in the session, or from the shell:

claude --desktop --resume <session-id>

Both need a Claude subscription sign-in and work on macOS and x64 Windows; --desktop needs Claude Code v2.1.285 or later.

Retention and deleting old sessions

Claude Code deletes transcripts older than cleanupPeriodDays, 30 days by default, in a silent background sweep. A session you have not touched for longer than that is gone from the picker. Sessions you started or last continued in the desktop app are kept at any age unless you set desktopSessionCleanupPeriodDays (Claude Code v2.1.248 and later). To keep history longer, raise it in ~/.claude/settings.json:

{
  "cleanupPeriodDays": 90
}

To clear one project's history sooner, claude purge deletes its transcripts, auto memory and related state after showing you what it will remove and asking for confirmation. claude purge --all does the same for every project. Transcripts are plain text and contain whatever passed through a tool, so purge before handing a machine on.

Third-party session managers and what they rely on

A community session manager that parses the transcript files directly can break on any release, because the Claude Code documentation says their format is internal and changes between versions. The documented interfaces include claude agents --json for live state, claude -p --resume <session-id> --output-format json for asking an existing session a question, the transcript_path field that hooks and status line commands receive, and the Agent SDK. /export gives a person a readable copy. Before installing a manager, check which of these it uses and whether it has kept up with recent releases.

Where Armadai fits

Everything above manages Claude Code sessions. If you also run Codex, the gap is one place that shows both, next to the code they are working on. Armadai is a native macOS app that turns each project folder into a workspace on one infinite canvas, with Claude Code and Codex agents, terminals, code and a browser side by side.

Its session sidebar lists sessions across all your projects as working, idle or needing approval. You can hover a waiting session, read the request and approve it from the sidebar without leaving the workspace in view; for prompts the sidebar cannot handle, you open the session directly. Its Codex Agent tile can find and resume saved Codex conversations and fork from a response. With the background session helper turned on, choosing Keep Running and Quit leaves terminals and CLI agents running after you close the app, and they reconnect when you reopen it.

Armadai uses your own Claude Code and Codex accounts, so their limits still apply. It is a paid app with no free plan: $20 a month or $120 a year after a 7-day free trial that requires a payment method. If you work in one repository with Claude Code alone, the picker and agent view are enough.