@boe-ventures/agent-replay
v0.2.1
Published
Local session recording for AI coding agents — captures DOM mutations, console logs, network requests, and errors from your dev server into structured JSONL files that agents can read directly
Downloads
492
Maintainers
kristianeboeReadme
@boe-ventures/agent-replay
Local session recording for AI-assisted development. Gives coding agents the same observability into a running web app that a human developer gets — console errors, network requests, DOM state, React component tree — but structured, programmatic, and cheap.
Why
AI coding agents today debug web apps by taking screenshots and feeding them to a vision model. That's expensive, slow, and lossy — you can't see network errors, console logs, or timing from a screenshot.
Session recording captures everything that happens inside the app. The agent gets structured data instead of pixels. The human developer gets a video-like replay for review.
How it works
Agent writes code → Dev server reloads
↓
AgentReplayProvider captures:
• DOM mutations (rrweb)
• Console logs/errors
• Network requests/responses
• React component tree + state
• User interactions (clicks, inputs, navigation)
↓
Events written to .agent-replay/
↓
┌────────────────────┴────────────────────┐
│ │
Agent reads structured events Human views replay
(file, CLI, or MCP tool) (npx agent-replay view)Quick start
npm install @boe-ventures/agent-replayReact (Next.js, Vite, Remix)
// app/layout.tsx
import { AgentReplayProvider } from "@boe-ventures/agent-replay/react";
export default function Layout({ children }) {
return (
<html>
<body>
<AgentReplayProvider>
{children}
</AgentReplayProvider>
</body>
</html>
);
}The provider auto-disables in production. Only records in development.
Sidecar server (framework-agnostic)
# Run alongside your dev server
npx agent-replay dev
# Or with a specific port
npx agent-replay dev --port 3700The sidecar receives events from the browser and writes them to .agent-replay/.
Next.js optimized
// next.config.ts
import { withAgentReplay } from "@boe-ventures/agent-replay/next";
export default withAgentReplay(nextConfig);Auto-injects the provider and API route. Zero config.
Agent consumption
Flat files (works with any agent)
.agent-replay/
sessions/
2026-04-25T1430Z/
events.jsonl # Full rrweb event stream
console.jsonl # Console logs/errors only
network.jsonl # Network requests/responses only
errors.jsonl # Errors only (highest signal)
react-tree.json # React component tree snapshot
summary.md # LLM-friendly text summary
latest -> sessions/2026-04-25T1430Z/Tell the agent: "Check .agent-replay/latest/errors.jsonl for recent errors" or "Read .agent-replay/latest/summary.md for a session overview."
Separate files so the agent can choose what to look at without exhausting context.
CLI
# Get a text summary of the last session
npx agent-replay summary
# Get just errors
npx agent-replay errors
# Get network failures
npx agent-replay network --failures
# Watch for new events (streaming)
npx agent-replay watchMCP tool (future)
{
"tool": "agent_replay_session",
"description": "Get the latest session recording events",
"parameters": {
"type": { "enum": ["summary", "errors", "network", "console", "all"] }
}
}What gets captured
| Signal | Source | File | Agent value | |--------|--------|------|-------------| | DOM mutations | rrweb | events.jsonl | Full page reconstruction | | Console logs | rrweb console plugin | console.jsonl | Errors, warnings, debug output | | Network requests | rrweb network plugin | network.jsonl | API failures, slow responses | | Errors | window.onerror + unhandledrejection | errors.jsonl | Highest signal — read this first | | User interactions | rrweb | events.jsonl | Clicks, inputs, navigation | | React tree | React DevTools hook | react-tree.json | Component state, props, context | | Route changes | Next.js router / History API | console.jsonl | Navigation flow |
Video replay
Recordings can be converted to video for human review:
# Generate video from a session
npx agent-replay video .agent-replay/latest
# Or decompose into frames (for vision model analysis via vidgrid)
npx agent-replay frames .agent-replay/latest --fps 1Chrome Extension (zero-config)
The Chrome extension records any localhost page automatically — no npm install, no provider component, no code changes.
Install from source
cd extension
pnpm install
pnpm buildThen load in Chrome:
- Open
chrome://extensions - Enable "Developer mode"
- Click "Load unpacked"
- Select
extension/.output/chrome-mv3/
What it does
- Auto-injects rrweb + console/network recording on
localhost:*and127.0.0.1:* - Streams events to the sidecar server (
npx agent-replay dev) every 2 seconds - Shows recording status, event count, and sidecar connection in the popup
- Badge shows "REC" on tabs being recorded
Works with the npm package
If <AgentReplayProvider> is already active on the page (sets window.__AGENT_REPLAY_ACTIVE__), the extension defers — no double recording. Both write to the same .agent-replay/ directory via the sidecar.
Development
cd extension
pnpm dev # starts WXT dev mode with hot reloadDesign principles
- Local-first. No cloud, no accounts, no telemetry. Files on disk.
- Dev-only. Auto-disabled in production. Zero runtime cost when off.
- Agent-first, human-friendly. Structured data for agents, visual replay for humans.
- Separate files per signal. Agent picks what it needs. No context exhaustion.
- Framework-agnostic core. Next.js adapter for convenience. Works with Vite, Remix, CRA.
- Composable with agent-browser. Agent-browser gives the outside view (accessibility tree, element refs). Agent-replay gives the inside view (errors, network, state). Together they're complete.
Interplay with agent-browser / Puppeteer
agent-browser ←→ Browser ←→ agent-replay
(outside) (inside)
agent-browser: "Click button @e3"
"Snapshot accessibility tree"
"Get page title"
agent-replay: "Console error at checkout.tsx:47"
"POST /api/checkout returned 500"
"React state: cart.items = []"Agent-browser drives the browser. Agent-replay observes what happens inside. The agent uses both.
License
MIT — Boe Ventures