How to Review an AI Coding Session (Not Just the Diff)

aq.dev / guides / how-to-review-an-ai-coding-session

How to review an AI coding session, not just the diff

Published July 29, 2026 · by the AQ team

AQ is the multiplayer coding harness: your whole team and every agent CLI in shared live workspaces, in your own cloud. Free on your own VM.<br>Start free →

Reviewing an AI coding session means evaluating the run that produced the code, not only the diff it left behind. A full session review covers five layers: the brief the agent was given, the corrections it received mid-run, the paths it tried and abandoned, the warnings the operator waved past, and the behavior of the running result. You can practice it today with any terminal agent and no special tooling, using three habits: preserve the original brief, keep the session transcript retrievable, and make a second person the default on agent pull requests. This guide walks through the manual practice first, then looks at where tooling removes the friction.

Why the diff alone is not enough

Classic code review assumes the author's thinking is visible in the diff. With agent-written code that assumption breaks: the quality-determining decisions happen during the run (how the task was scoped, what the agent misunderstood, what the operator let slide), and the diff records only their outcome. That is the premise behind session review as a practice distinct from code review.

The gap is no longer hypothetical. 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 only about one in eight workflows involved multiple humans. Most agent work merges with exactly one set of eyes on it, and that reviewer carries expectation bias: they know what was asked, so they read the diff as confirmation. The characteristic agent failure (plausible code that does something subtly different from the request) is precisely the failure that bias hides. The full argument is in the self-review problem; this guide is the how-to.

Habit 1: preserve the original brief

The single highest-leverage change costs thirty seconds: paste the prompt that started the session, verbatim, into the pull request description. Not a summary, the actual text. A reviewer who can compare the brief against the diff can answer the question no amount of code reading answers: does this change implement what was actually asked?

Three rules make the habit stick:

Verbatim beats summarized. A paraphrase of the prompt inherits the same expectation bias the review is trying to remove. Copy the real text, typos and all.

Include the corrections that changed scope. If you redirected the agent mid-run ("no, only the API layer", "skip the migration for now"), those follow-ups are part of the brief. A reviewer who does not know the migration was deliberately skipped will either waste time flagging it or wrongly assume it was forgotten.

The ticket is not the brief. Linking the issue is good practice, but the agent never read your intentions, it read your prompt. When the two diverge, the prompt explains the diff.

Habit 2: keep the transcript retrievable

Everything else in a session review depends on the transcript surviving until review time. By default it often does not: terminal scrollback dies with the window, and CLI history files expire. Decide, as a team, where transcripts live, and make saving one a reflex that happens before the PR is opened.

If the agent runs inside tmux (which also keeps the session alive when your connection drops), the scrollback is exportable with one command:

# from inside the pane: write the entire scrollback to a file<br>tmux capture-pane -p -S - > agent-session-fix-auth.txt

# or record everything from the start with the classic script utility<br>script -q agent-session.log

The agent CLIs themselves keep records, with different levels of convenience as of July 2026. Claude Code stores every session as JSONL under its projects directory and can resume it later with claude --continue or the claude --resume picker; more usefully for review, the /export command renders the current conversation to a plain-text file or the clipboard. Note the retention default: transcripts are cleaned up after 30 days unless you change the cleanup setting, so "it is in Claude Code somewhere" is not an archival strategy. Codex CLI similarly saves each session as a JSONL file under ~/.codex/sessions/ and reopens it with codex resume, though it has no built-in rendered export, so teams typically save the raw file or capture the terminal instead.

For sessions worth replaying rather than reading (a tricky debugging run, a session you want to teach from), asciinema records the terminal as a lightweight text-based cast a teammate can play back. Whatever the mechanism, the bar is the same: a reviewer asked to look at an agent PR should be able...