How to review Claude Code sessions

Updated October 28, 2026 · first published August 2, 2026 · by the AQ team

Reviewing a Claude Code session means reading the record of the run that produced the code: the brief, the corrections, the tool calls and their results, alongside the diff. As of October 2026, Claude Code keeps most of that record for you: every interactive session is saved continuously as a local JSONL transcript, listed in the claude --resume picker, findable from the pull request it created, resumable by name or generated title, exportable to readable text with /export, and answerable from a script with claude -p --resume. The one gap is the second reviewer: the transcript sits in the operator's home directory on the operator's machine, nothing in the CLI lets a teammate open it, and the retention sweep deletes it after 30 days by default. This guide covers what Claude Code preserves today, how a reviewer gets at it, what the record can and cannot prove, and the workarounds that close the gap.

Why the session matters and the diff is not enough

The decisions that determine an agent PR's quality (how the task was briefed, where the agent was corrected, which warnings the operator waved past) happen during the run, and the diff records only their outcome. That is the premise of session review, and the gap is measured: a July 2026 LeadDev analysis of 25,264 agent-generated pull requests across 2,361 popular GitHub repositories found that in 79 percent of agentic PRs the same developer both reviewed and modified the agent's contribution, and just one in eight workflows involved multiple humans. The full argument is in the self-review problem; the general method is in how to review an AI coding session. This page is about what Claude Code specifically hands a reviewer.

What Claude Code preserves, as of October 2026

Claude Code saves every interactive session continuously, without being asked. The record is a JSONL transcript at ~/.claude/projects/<project>/<session-id>.jsonl, where <project> is the working directory path with non-alphanumeric characters replaced by hyphens. Each line is a message, a tool use or result, a record of a request Claude Code sent the model, or a metadata entry, so the file holds your prompts, the model's replies, every tool call with its result, and the system prompt and tool definitions the model was given. Subagent transcripts sit beside it under <session-id>/subagents/. The properties that matter for review:

• Sessions are listed and resumable. claude --continue reopens the most recent session in the current directory; claude --resume opens the session picker, or resumes a session directly when you pass a name, a generated title, a session ID, or the absolute path of its .jsonl file. Inside a session, /resume switches to another one. Sessions started with claude -p or the Agent SDK are left out of the picker and of claude --continue; resume those by session ID.
• The picker searches and widens. Each row shows the session's name or generated title, the time since its last activity, its git branch and its file size. Press Space to preview a session's content, type to search, Ctrl+B to filter to the current git branch, Ctrl+W to widen to every worktree of the repository, Ctrl+A to widen to every project on the machine, and Ctrl+R to rename the highlighted session.
• Names and titles are resume handles. claude -n names a session at launch and /rename names it mid-run. An unnamed session gets a generated title (a short summary of the first prompt), and accepting a plan replaces it with a title based on the plan; either title works with claude --resume or /resume. The default display name shown in listings of running sessions, such as my-app-3f, does not resume anything.
• Branches get their own records. /branch copies the conversation so far into a new session with its own ID and leaves the original intact; claude --continue --fork-session or claude --resume --fork-session does the same from the shell. Both appear as separate rows in the picker. If you resume the same session in two terminals without forking, messages from both interleave into one transcript, which is worth knowing before you read one.
• /clear does not discard anything. Claude Code saves the previous session when you run /clear; reopen it with /resume, or from the previous-session entry at the top of the /rewind menu in the same process.
• Checkpoints ride along. Claude Code snapshots the code state before each prompt that starts a turn, keeps snapshots for the 100 most recent checkpoints, and saves them with the conversation, so /rewind still works after a resume. Checkpoints track files Claude edited with its own file editing tools. A file that only shell commands changed is not tracked, and edits by subagents are usually not captured.
• Retention is 30 days by default. The retention sweep deletes transcripts, subagent transcripts, checkpoint snapshots, plans and debug logs older than cleanupPeriodDays (default 30, minimum 1). For review this is the sharpest edge in the system: a transcript that existed when the PR was opened can be gone by the time anyone asks about it.

One caution: the JSONL entry format is internal to Claude Code and changes between versions, and the docs say scripts that parse the files directly can break on any release. For anything durable, use /export and the script interfaces below.

The reviewer's toolkit

Seven mechanisms turn a stored session into something a reviewer can read.

1. /export renders the transcript. Inside a session, /export opens a menu to copy the conversation to the clipboard or save it as a plain-text file, with messages and tool outputs rendered as readable text. Pass a filename to skip the menu. This is the standard way to produce a review artifact:

# inside the session, write a readable transcript to a file
/export review-fix-auth.txt

2. The picker finds the run behind a pull request. In the claude --resume picker, paste a GitHub, GitHub Enterprise, GitLab or Bitbucket pull or merge request URL into the search to find the session that created it, and press Space to preview it before opening. There is also a direct flag:

# open the picker filtered to sessions linked to PR 142
claude --from-pr 142

For a reviewer at the operator's machine (or pairing over a screen share), this answers the first question of any session review, which run produced this change, in seconds.

3. Headless mode asks a finished session a question. Pass a session ID to claude -p --resume to send a follow-up prompt and capture the structured answer. The docs' own example asks for a summary; a reviewer can ask sharper questions:

claude -p --resume SESSION_ID --output-format json \
  "List every place I corrected you mid-run, verbatim" | jq -r '.result'

Two things to know. The answer is the model's account of its own transcript, so treat it as a pointer into the record rather than the record itself. And if the session is a background session that is still running, a command with --output-format json sends nothing and exits with status 1; stop the session first, or use claude logs for its recent output.

4. Hooks hand you the transcript path. Every hook receives transcript_path in its input, and a SessionEnd hook runs when a session ends, with a reason of clear, resume, logout, prompt_input_exit or other. That is the archive point: copy the file to a shared location before the sweep can reach it. SessionEnd hooks get 1.5 seconds by default; set a per-hook timeout (the budget rises to match it, up to 60 seconds) or CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS if the copy needs longer. The transcript is written asynchronously, so a hook that fires mid-turn may read a file that lags the conversation by a message.

5. Agent view lists background sessions. Sessions sent to the background keep running without a terminal. claude agents opens agent view, one screen that lists them grouped by state, with a one-line summary per row generated by a Haiku-class model; Space opens a peek panel with the session's most recent output. claude attach <id> opens one in your terminal, claude logs <id> prints its recent output, and claude agents --json --all prints every session as JSON with its state, status and what it is waiting for, which the docs name as the supported way to read session state from outside Claude Code. For a reviewer, agent view answers what the session is doing now; the transcript under projects/ is still the record of what it did. Background sessions are marked bg in the resume picker, and claude --continue opens a finished one (Claude Code v2.1.257 or later).

6. The desktop app picks up CLI sessions. The Claude Code desktop app keeps its own session list, with grouping, sorting and an archived tab. Typing /resume in its prompt box lists the sessions started from the CLI on that computer, searchable by title, folder or branch with a preview of where each left off, and continues the same session rather than a copy. From the shell, claude --desktop --resume <session-id> opens one directly (Claude Code v2.1.285 or later, macOS and x64 Windows, signed in with a Claude subscription). It is a nicer reading surface for the operator; it does not change who can reach the session.

7. tmux holds the raw scrollback. If the session ran inside tmux (a good idea anyway, since tmux keeps it alive across disconnects), the terminal history is exportable independently of Claude Code:

tmux capture-pane -p -S - > raw-session-scrollback.txt

The transcript and the scrollback overlap and are not identical: the transcript is the conversation as Claude Code recorded it, the scrollback is what the operator saw, including anything that happened outside the agent. One exception: an attached background session renders fullscreen and has no terminal scrollback, so capture-pane returns only the current viewport there; use /export or the transcript instead.

What survives the end of a session

Three settings decide whether a transcript exists at all, and a reviewer should check them before concluding that a run was never recorded: CLAUDE_CODE_SKIP_PROMPT_HISTORY suppresses transcript writes in every mode, --no-session-persistence suppresses them for one claude -p run, and CLAUDE_CODE_TRANSCRIPT_LOCAL_GC limits how large a claude -p or Agent SDK session's transcript file grows. Transcripts of sessions started or last continued in Claude Desktop or Cowork are kept at any age unless desktopSessionCleanupPeriodDays sets a limit (Claude Code v2.1.248 or later). claude purge deletes a project's transcripts, auto memory, checkpoint snapshots and prompt history on demand, after printing its plan and asking for confirmation (before v2.1.288 the command was claude project purge). Deleting a background session with claude rm removes it from agent view and, when safe, the worktree Claude created for it; the transcript stays on disk and remains available through claude --resume.

What a session record can and cannot prove

The security case for session review is concrete: an agent run that touched production credentials, ran a destructive command, or was steered past a warning. A reviewer asked "what did the agent actually do" needs to know what the record covers.

What the transcript records. Every prompt, every reply, every tool call Claude Code made with its result (file reads and edits, shell commands and their output, MCP tool calls), the system prompt and tool definitions sent with each request, and subagent transcripts. Checkpoint snapshots add the pre-edit contents of files Claude edited with its own tools.

What it does not record. Commands the operator ran in another pane or another terminal; changes made by a shell command rather than by Claude's file tools, which the transcript shows only as that command's output; the state of files a subagent edited, which checkpoints usually skip; and anything after the retention sweep has run. The web and desktop apps, Remote Control, and Claude Code on the web each keep their own session lists, so a run may have left its record somewhere other than the directory you are looking in.

Assumptions. Storage is operator-side: the file is in the operator's home directory, on the operator's machine, with ordinary file permissions. The operator (or anyone with their account) can edit the JSONL, delete it, lower cleanupPeriodDays, run claude purge, or set CLAUDE_CODE_SKIP_PROMPT_HISTORY so no file is written. A transcript is evidence of what Claude Code recorded on a machine you trust; it is not evidence against a person who controls that machine.

Failure modes. The transcript expired before the question was asked. A script parsed the internal JSONL format and broke, or silently misread it, after a release changed it. An /export file or a transcript copied to a shared drive carried secrets: tool output includes whatever a command printed, and the web sharing docs warn that sessions may contain code and credentials from private repositories. A heap snapshot written by /heapdump contains the full conversation and any credentials the process held, and neither the sweep nor claude purge removes it.

Checks a reviewer can run. Each is reproducible on the operator's machine:

1. Locate the record: list ~/.claude/projects/ for the project directory, then the session's .jsonl by ID, or open claude --resume, paste the PR URL, and press Space to preview the matching session.
2. Render it: resume the session and run /export with a filename, then read the tool calls in order.
3. Ask it: claude -p --resume <session-id> --output-format json with a question such as "list every shell command you ran that modified files outside this repository", then verify each answer against the export.
4. Compare with what the operator saw: tmux capture-pane -p -S - from the pane the session ran in, if it ran in tmux and the server is still up.
5. Check for the blind spots: git log and git status in the worktree for changes the transcript cannot explain, and the environment for CLAUDE_CODE_SKIP_PROMPT_HISTORY or a lowered cleanupPeriodDays.

The gap: none of this reaches a second reviewer

Everything above is operator-side. The transcript sits in the operator's home directory on the operator's machine; the resume picker, the PR lookup, agent view, the desktop app and /rewind all run there too. As of October 2026, the Claude Code docs describe no way for a teammate to open a local CLI session. What sharing exists:

• Claude Code on the web shares cloud sessions. A session at claude.ai/code can be set to Team visibility on Enterprise and Team accounts (visible to other members of the claude.ai organization, with repository-access verification on by default) or to Public on Pro and Max accounts (visible to any user logged into claude.ai), and then opened by link. Recipients see the latest state when they open the link; their view does not update in real time. This covers sessions that ran in Anthropic's cloud, which is the subject of Claude Code cloud sessions explained. It does not cover a session that ran in a terminal.
• Remote Control is for the operator's own devices. It connects your phone or browser to your own running local session, and the docs are explicit that it signs in with your own claude.ai account, appears only in your own account's Claude apps, and grants no one else access. It lets you continue your own session from another device; it does not let a teammate read it.
• The desktop app and agent view are local too. Both read the sessions on the computer they run on, under the same account.
• Retention works against review. Deleting transcripts after 30 days is reasonable for privacy and wrong for audit: the sessions most worth reviewing (the ones behind a regression discovered weeks later) are exactly the ones most likely to have expired.

So a second reviewer sees whatever the operator remembered to export, and nothing else. That is the self-review problem restated as a tooling default.

Workarounds that close the gap

• Make /export part of opening a PR. Export the transcript and put it where reviewers already look: a shared drive, an internal wiki, or the PR itself. Paste the original brief verbatim into the PR description either way. Be deliberate about destinations, since transcripts can contain secrets and internal paths.
• Automate the archive with a SessionEnd hook. The hook receives transcript_path and can copy the finished transcript to a shared location without anyone remembering to do it. Give it a timeout long enough for the copy. This converts "the operator usually exports" into "every session is archived".
• Raise cleanupPeriodDays in settings.json on machines that run agent work, so the local record outlives the review cycle. Set desktopSessionCleanupPeriodDays deliberately on the same machines, since desktop and Cowork transcripts otherwise follow a different rule.
• Name sessions after the work. claude -n fix-auth-142 at launch, or /rename later, gives a reviewer a handle that resumes directly and reads sensibly in the picker weeks later.
• Run sessions in tmux on a shared machine. A team dev box with tmux gives reviewers what Claude Code alone cannot: attach to a session, watch it live, and capture scrollback themselves, with access controlled by SSH.
• Review in layers. With a transcript in hand, work through the brief, the corrections, the abandoned paths, the overrides, and the running behavior. The session review checklist has concrete questions for each layer, and resume and search Claude Code sessions covers finding the right session in the first place.

Where AQ fits

AQ is the multiplayer coding harness where engineering teams run AI coding agents like Claude Code and Codex together: shared live terminals, a code editor, and app previews, in your own cloud. It is, in effect, the shared-tmux-box workaround turned into a product. Claude Code runs as the real CLI in an isolated git worktree on a machine dedicated to your team, in a live workspace teammates join from a link: a work item is one task, one branch and worktree, and the session survives a closed laptop. The part Claude Code cannot do on its own is the part AQ exists for: a teammate opens the same workspace and watches the same live session, scrollback included, with no export step and no access to the operator's machine. Workspace visibility stays owner-managed, each engineer signs in to Claude Code with their own account, and AQ never marks up usage on your own subscriptions.

The rest of the review happens in the same place: the reviewer reads the diff, comments on lines and merges from the Changes panel, clicks through the live app preview, and can pin comments on the preview that are routed back to the agent. The session, the diff, and the result stay one link apart.

Start with what Claude Code already gives you: /export on every agent PR, a SessionEnd archive hook, named sessions and a longer cleanup period cost nothing and work today. Move the sessions somewhere shared when the export ritual starts failing under deadline, because that is the week it matters most.