> ## Documentation Index
> Fetch the complete documentation index at: https://subtext.fullstory.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Session Review: AI Agent Debugging from Real Sessions

> Session Review lets your AI agent open real production sessions, step through events, capture UI snapshots, and compare state — without human scrubbing.

Your AI agent can read every line of your codebase, but until now it had no way to see what your application actually does when a real user is in it. Session Review closes that gap. Point your agent at a production session and it opens the recording, reads the event map, zooms in on the moments that matter, and explains exactly what went wrong — all without you scrubbing through a timeline by hand.

## What Session Review is

Subtext isn't another coding agent. It's the session replay your agent has been missing. You bring the understanding of the codebase; Subtext supplies the session context — the event stream, the UI state at any timestamp, and a semantic map of your app's components tied back to source files.

When you run a session review, your agent:

* Opens a real production session and receives a handle, an event map, and a digest rollup of what happened.
* Reads the map to understand the shape of the session before spending tokens on detail.
* Zooms into specific time windows with configurable resolution to see exactly what the signal stream looked like at the moment of interest.
* Captures a visual snapshot — screenshot, component tree, and bounding boxes — at any timestamp.
* Compares state across moments to surface regressions, unexpected transitions, or missing UI updates.
* Closes the session and records feedback when the investigation is complete.

<Note>
  Session Review works with recordings captured by the Fullstory snippet. If you haven't installed the snippet yet, start with the [install guide](https://subtext.fullstory.com/install).
</Note>

## Bring your own agent

Subtext connects over MCP (Model Context Protocol), so it works with any agent that speaks MCP. Tested and supported agents include:

* **Claude Code** — invoke skills directly from the chat pane
* **Cursor** — wire up the MCP server in your Cursor settings
* **Codex** — pass the MCP config via environment or config file
* **Your own harness** — any MCP-compatible client works; no proprietary SDK required

## Core capabilities

<CardGroup cols={2}>
  <Card title="Find sessions" icon="magnifying-glass">
    `review-list-sessions` returns a numbered list of reviewable sessions with URLs and timestamps — so your agent knows what's available before it commits to opening one.
  </Card>

  <Card title="Open & orient" icon="folder-open">
    `review-open` hands your agent a session handle, the full event map, and a digest rollup. If a sightmap is configured, it also returns a `sightmap_upload_url` so component names resolve in every subsequent snapshot.
  </Card>

  <Card title="Summarize" icon="list">
    `review-summary` returns a static, frozen "what happened" summary at the default zoom level — useful as a cheap first read before zooming into specifics.
  </Card>

  <Card title="Zoom in" icon="crosshairs">
    `review-zoom` is the live lens. Set a resolution and a time window to pull a higher-fidelity slice of the signal stream over any interval in the session.
  </Card>

  <Card title="Snapshot" icon="camera">
    `review-snapshot` returns the screen at a specific moment: a screenshot, the component tree with element UIDs, and bounding boxes. Pair it with the sightmap for semantic names instead of raw selectors.
  </Card>

  <Card title="Close & record" icon="circle-check">
    `review-close` closes the session and records structured feedback — keeping a clean audit trail of what your agent investigated and what it concluded.
  </Card>
</CardGroup>

## The `/subtext:review` workflow

The fastest way to run a full investigation is the `/subtext:review` skill. Type it in your agent's chat and it runs a structured workflow end-to-end:

<Steps>
  <Step title="List available sessions">
    The agent calls `review-list-sessions` to see what recordings are available and picks the relevant one based on your prompt.
  </Step>

  <Step title="Open and read the map">
    `review-open` returns the event map and digest. The agent reads the map to understand the session's shape — what pages were visited, what events fired, where things look unusual — before spending tokens on detail.
  </Step>

  <Step title="Zoom to the moments that matter">
    The agent calls `review-zoom` one or more times, narrowing the time window and increasing resolution around the events most relevant to your question.
  </Step>

  <Step title="Capture snapshots for evidence">
    At key timestamps, `review-snapshot` captures the visual state — screenshot plus component tree — so the agent can describe exactly what the user saw.
  </Step>

  <Step title="Explain what happened">
    The agent synthesizes the event stream, snapshots, and its knowledge of the codebase into a plain-English explanation, including a hypothesis about root cause and suggested next steps.
  </Step>

  <Step title="Close the session">
    `review-close` finalises the session and records feedback so the investigation is logged.
  </Step>
</Steps>

<Tip>
  You don't have to run the full skill every time. If you already know which session you want, you can call `review-open` directly and drive the investigation yourself — or ask your agent to zoom into a specific timestamp without running the complete workflow.
</Tip>

## What the sightmap adds

If your project has a `.sightmap/` directory, every snapshot your agent receives is enriched with semantic context: component names, source file paths, visibility flags, interactivity flags, and bounding boxes. Instead of reasoning about `div.sc-4f8a9b > button:nth-child(2)`, your agent sees `AddToCartButton (src/components/AddToCart.tsx)`. That context dramatically reduces the number of tokens and tool calls needed to identify what's on screen and where the problem is.

Session Review works without a sightmap, but investigations are faster and more accurate with one. The open-source sightmap schema is coming soon.