Debugging with Replay: Replay in Claude Code

The Replay plugin for Claude Code bundles what an agent needs to test your app with Replay:

a skill that drives Replay Chromium with playwright-cli
hooks that upload the recordings
Replay MCP for debugging them
inline live players: every browser the agent opens appears in the conversation, live while it runs and scrubbable once it closes

Install

The plugin records with the replayio CLI. Install Replay Chromium and sign in once:

Terminal
npx @replayio/replay install
replayio login

Add the plugin to your project

From your project's root directory, run:

Terminal
npx shadcn@latest add replayio/plugins/claude-pro

This installs the plugin into .claude/skills/replayio/, and its worker and critic subagents into .claude/agents/. Claude Code loads it the next time you start claude in this directory. To load it explicitly for one session, run claude --plugin-dir .claude/skills/replayio.

Turn on function hooks for the live players

The live players are a Claude Code hooks module, which needs function hooks enabled. Add this to ~/.claude/settings.json:

~/.claude/settings.json
{
  "env": { "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS": "1" }
}

Recording, uploading and Replay MCP work without it. Only the players need it.

Start Claude Code in a supported terminal

The inline picture uses the kitty graphics protocol. Run claude in Ghostty or kitty. In other terminals, the player row shows its controls and an Open in browser button instead of the picture.

Requirements

The players render in a headless Google Chrome or Chromium, so install one of those (set REPLAY_LIVE_CHROME to choose a binary). Saving a video also needs ffmpeg. Function hooks are an early Claude Code API and can change between releases. If an update breaks the players, the rest of the plugin keeps working.

Watch the agent's browser live

Ask Claude to test something in the browser, for example "Open http://localhost:3000, sign up, and check the dashboard loads." When the agent opens a browser with playwright-cli, the result of that command becomes a player:

While the browser runs, the player follows the page live: clicks, typing, navigation, and the cursor. Errors the page throws appear under the picture.
When the agent closes the browser, the player stops on the last frame and turns into a scrubbable recording.

Each browser session gets its own player, attached to the command that opened it, so you can scroll back through a long conversation and replay any of them.

Scrub through a recording

Control	What it does
Seek bar	Click or drag to jump to that moment. After clicking it, Space plays or pauses and ← / → step 5 seconds.
⏮ / −10s / +10s	Jump to the start, or back or forward 10 seconds.
▶ Play / ❚❚ Pause	Play from the current position. Idle stretches are skipped.
▶ Replay so far	While the browser is still running, scrub what has been recorded so far.
Open in browser	Open the full player in your browser, with a seek bar and 1×–8× speed.

Save a recording as a video

Click ⤓ Save video on a player, or run /replay-live save <session-name> in Claude Code. This writes two files to .replay/live/ in your project, named after the session's start time and session name:

<start>-<session>.mp4: a 15 fps video, with idle stretches over two seconds shortened.
<start>-<session>.rrweb.json: the raw rrweb events, which any rrweb player can load.

Use /replay-live save latest to save the most recent session.

Find older recordings

Every recording is kept under ~/.claude/replayio-live/. Players stay playable after you restart Claude Code or resume the conversation.

/replay-live lists recordings from every session, newest first, with a link to play each one.
/replay-live library opens a page in your browser with every recording. Each can be played, downloaded as .rrweb.json, or saved as an MP4.

How the live players work

When the agent runs a playwright-cli … open command, the plugin adds the Replay session recorder to every page in that browser session. The recorder captures rrweb DOM events along with network, storage and websocket activity, and streams them to a small server the plugin runs on 127.0.0.1. That server stores the recording and replays it in a headless browser. Claude Code shows the replayed frames in the conversation.

The live player is a view of the page, not a Replay recording. To debug with time travel, use the Replay recording that Replay Chromium uploads when the browser closes, through Replay MCP or Replay DevTools.

Troubleshooting

No player appears. Check that CLAUDE_CODE_ENABLE_FUNCTION_HOOKS is 1 in the environment claude was started with, and that the agent opened the browser with playwright-cli from a Bash command. /replay-live reports whether the plugin's local server is running.
The row shows controls but no picture. Your terminal does not support kitty graphics. Use Open in browser, or switch to Ghostty or kitty.
"No Chrome/Chromium found for the inline player". Install Google Chrome or Chromium, or set REPLAY_LIVE_CHROME to the browser binary.
Save video fails. Install ffmpeg and make sure it is on your PATH.