Managing Claude Code sessions and context

Who this is for and what you will be able to do

This guide is for people who juggle several tasks in one project and notice that long conversations start to drift. After reading it, you will know how to resume an earlier session, name sessions so they are easy to find, branch a conversation to test another approach, and decide when to use /clear versus /compact.

What a session is

In Claude Code, a session is a saved conversation tied to a project directory. Claude Code writes it to local storage while you work, so you can come back after exiting or after running /clear^[1]. Transcripts are stored as JSONL files under ~/.claude/projects/, and the project folder name is derived from the working directory^[1].

The desktop app, claude.ai/code, and the VS Code extension each keep their own session lists. This guide covers the command-line version^[1].

Resuming an earlier session

These entry points are the ones you will use most:

• claude --continue reopens the most recent session in the current directory^[1].
• claude --resume opens the session picker.
• claude --resume <name> resumes a named session directly^[1].
• claude --from-pr <number> filters the picker to sessions linked to a pull request^[1].
• Inside a session, /resume switches to a different one^[1].

A resumed session brings back the conversation history, tool calls, and results. If the previous process crashed while a tool was running, that tool call is not run again^[1].

Some launch flags do not carry over. If the session relied on --mcp-config, --settings, --plugin-dir, --fallback-model, or --add-dir, pass them again^[1].

From a terminal, the permission mode the session ended in is restored as well. Use --permission-mode or --dangerously-skip-permissions to change it^[1].

Background subagents, background Bash commands, and workflows that were still going when the process ended show up as notes saying they did not finish. Claude Code does not start a turn on its own from those notes. Claude reads them when you send your next prompt^[1].

Naming sessions

Descriptive names make the picker usable when you run several tasks at once. You can set a name at startup with claude -n auth-refactor, inside a session with /rename auth-refactor, or from the picker by highlighting a session and pressing Ctrl+R^[1].

Unnamed sessions get two labels. The first is a default display name built from the folder name and a two-character suffix, such as my-app-3f. It helps you tell running sessions apart, but it does not work as a resume handle^[1]. The second is a generated title, a short summary of the first prompt written by a small, fast model, usually a Haiku-class model. A claude -p run started from a shell or script does not get one^[1].

The picker has useful shortcuts. Press / to search, Ctrl+A to list sessions from every project on the machine, Ctrl+W to list sessions from all worktrees of the current repository, and Ctrl+B to filter by the current git branch^[1].

Branching to try another approach

When you want to test a different route without losing the current conversation, branch it. Inside a session, run /branch with an optional name:

/branch try-streaming-approach

Without a name, the new branch takes its name from the first prompt. /branch copies the conversation up to that point and moves you into the copy. The session you branched from stays on disk and remains in the picker^[1].

From the command line, combine --continue or --resume with --fork-session:

claude --continue --fork-session

Be careful not to resume the same session without forking in two terminals. Messages from both would interleave in a single transcript^[1]. If you want two lines of work, fork.

Managing context: /clear, /compact, and compaction

The context window holds everything Claude knows about the session so far: your instructions, the files it has read, and its own replies^[2]. A few commands help:

• /clear empties the context and starts over. The previous session is saved and you can return to it with /resume^[1]. It is the cleanest choice when you switch to unrelated work.
• /compact [instructions] replaces the history with a summary and accepts a note about what to keep. For example, /compact focus on the auth bug fix steers the summary toward that fix rather than whatever automatic compaction would pick^[1][2].
• /context shows how much context each category is using^[1].

Claude Code compacts on its own as the limit approaches. The automatic pass summarizes the history and then reloads a set of items from disk: the project-root CLAUDE.md, unscoped rules, and auto memory^[2]. It also re-reads up to five of the files Claude touched most recently. Any file over 5,000 tokens comes back as a path reference rather than full content^[2].

Invoked skill bodies come back too, with a cap of 5,000 tokens per skill and 25,000 tokens overall. When the total budget is exceeded, the oldest invoked skills are dropped first^[2].

One detail is easy to miss. Path-scoped rules and nested CLAUDE.md files load into the conversation only when Claude reads or edits their trigger files. Compaction summarizes them away with everything else. If a rule must always apply, remove its paths: frontmatter or move it into the project-root CLAUDE.md^[2].

Delegating large reads to a subagent

Research that means reading many files is better handed to a subagent. It works in its own context window and returns only a summary and a small metadata trailer, which keeps the main conversation lean^[2].

Reading sessions from scripts

/export produces a readable transcript for people. For scripts, use a structured interface. The following command sends a follow-up prompt to an existing session and extracts the answer with jq:

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

Avoid parsing the .jsonl files directly. Claude Code's internal entry format changes between versions, so such scripts can break at any release^[1].

Limits and common problems

• Transcripts expire after 30 days by default. Change the retention with cleanupPeriodDays in settings.json if you need longer^[1].
• **Sessions from claude -p are hidden.** They do not appear in the picker and claude --continue skips them. Resume one by passing its ID to claude --resume <session-id>^[1].
• Resuming by ID works from any folder. Claude Code searches the current project and its worktrees first, then other projects on the machine^[1].
• Compaction is not a reset. Whether a rule survives depends on whether it has paths: frontmatter^[2].

Next steps

For the remaining details, including how sessions work with worktrees, see the official documentation^[1].