Agent Session Replayer

agent-session-replayer is an SSR-safe React component for replaying a fixed, scripted implementer/reviewer session. It does not run a model, invoke tools, or execute code: the whole story comes from the data you provide.

Install

bun add agent-session-replayer

React 18 and 19 are peer dependencies. Import the precompiled stylesheet once; consumers do not need Tailwind CSS.

import { AgentSessionReplayer, type AgentSession, type AgentSessionReplayerProps } from "agent-session-replayer";
import "agent-session-replayer/styles.css";

Development

This repository uses Bun and commits bun.lock as its lockfile.

bun install
bun run dev
bun run test
bun run typecheck
bun run build:package
bun run build

Minimal complete replay

import { AgentSessionReplayer, type AgentSession, type AgentSessionReplayerProps } from "agent-session-replayer";
import "agent-session-replayer/styles.css";

const agents: AgentSessionReplayerProps["agents"] = {
  implementer: {
    id: "claude-code",
    name: "Claude",
    role: "Implementer",
    context: "the repository and approved task",
  },
  reviewer: {
    id: "reviewer",
    name: "Review agent",
    role: "Adversarial reviewer",
    context: "the diff and acceptance criteria",
  },
};

const cases: AgentSession[] = [{
  id: "checkout-fix",
  title: "Fix checkout total",
  summary: "A deterministic implementation and review replay.",
  repository: "acme/storefront",
  branch: "fix/checkout-total",
  events: [{
    id: "task",
    type: "task_received",
    actor: "implementer",
    title: "Read the task",
    summary: "Confirm the requested checkout behavior.",
    blocks: [{
      id: "request",
      kind: "message",
      content: "Correct the checkout total and add a regression test.",
    }],
  }],
}];

export function Demo() {
  return <AgentSessionReplayer agents={agents} cases={cases} />;
}

Props

All objects are strict at runtime: unknown keys are rejected. Required strings must be non-empty. Invalid props throw during render with an error beginning AgentSessionReplayer received invalid props:.

| Prop | Type | Required / default | Rules and behavior | | --- | --- | --- | --- | | agents | Record<"implementer" \| "reviewer", AgentIdentity> | Required | Must contain exactly implementer and reviewer identities. | | cases | AgentSession[] | Required | Non-empty sessions. Case IDs are unique across the array. | | typingSpeed | number | 110 | Finite, greater than zero; graphemes revealed per second. | | eventDelayMs | number | 500 | Finite, zero or greater; delay between completed events. | | height | number | 720 | Finite, greater than zero; rendered as pixels. | | colors | AgentSessionColors | Optional | Scoped CSS-variable overrides listed below. | | caseIndex | number | Optional | Controlled case index. It must be an integer in the cases bounds. | | initialCaseIndex | number | 0 | Uncontrolled starting index. It must be an integer in the cases bounds. | | className | string | Optional | Added to the player root element. | | onCaseChange | (index, item) => void | Optional | Called only for user navigation requests; controlled parents must update caseIndex. | | onEventStart | (event, item) => void | Optional | Called once before an event reveals its first grapheme. | | onEventComplete | (event, item) => void | Optional | Called once after the event finishes revealing. Interrupted events do not complete. | | onCaseComplete | (item) => void | Optional | Called after the final event completion for a case. |

Controlled and uncontrolled navigation

Omit caseIndex to let the component own navigation. Use initialCaseIndex to start at another case.

<AgentSessionReplayer agents={agents} cases={cases} initialCaseIndex={1} />

Supply caseIndex to control navigation. The callback reports a request; the parent updates the value.

import { useState } from "react";

const [caseIndex, setCaseIndex] = useState(0);

<AgentSessionReplayer
  agents={agents}
  cases={cases}
  caseIndex={caseIndex}
  onCaseChange={(nextIndex) => setCaseIndex(nextIndex)}
/>

Replay data schema

AgentIdentity

| Field | Type | Rules | | --- | --- | --- | | id | string | Non-empty identity ID. | | name | string | Non-empty visible name. | | role | string | Non-empty visible role. | | context | string | Non-empty description of the agent's working context. |

AgentSession

| Field | Type | Rules | | --- | --- | --- | | id | string | Non-empty and unique across cases. | | title | string | Non-empty case title. | | summary | string | Non-empty case summary. | | repository | string | Non-empty repository label. | | branch | string | Non-empty branch label. | | events | AgentSessionEvent[] | Non-empty. Event IDs are unique within the case. |

AgentSessionEvent

| Field | Type | Rules | | --- | --- | --- | | id | string | Non-empty and unique within its case. | | type | AgentEventType | One of the event literals below. | | actor | "implementer" \| "reviewer" | Agent that produced the event. | | title | string | Non-empty event title. | | summary | string | Non-empty collapsed-event summary. | | blocks | AgentSessionBlock[] | Non-empty. Block IDs are unique within the event. |

AgentEventType is one of:

"task_received" | "plan" | "patch" | "review_request" | "review_start"
| "blocking_finding" | "revision" | "verification" | "approval"

AgentSessionBlock

| Field | Type | Rules | | --- | --- | --- | | id | string | Non-empty and unique within its event. | | kind | AgentBlockKind | One of the block literals below. | | title | string | Optional; when supplied it must be non-empty. | | content | string | Non-empty visible block content. | | language | string | Optional; when supplied it must be non-empty. |

AgentBlockKind is one of:

"message" | "code" | "tool_call" | "tool_output" | "finding" | "patch" | "git_diff" | "status" | "result"

Lifecycle ordering

For each replayed event, onEventStart(event, case) fires once before text starts revealing, then onEventComplete(event, case) fires after its final grapheme. On the final event, onEventComplete fires before onCaseComplete(case). Restarting or navigating to a case begins a new run and may fire the callbacks again for that run.

Validation failures

The component validates the resolved props, including defaults, immediately before playback starts. It reports all detected issues in one error with nested paths.

// Throws: AgentSessionReplayer received invalid props:
// cases[0].events[0].blocks[0].content: Too small: expected string to have >=1 characters
<AgentSessionReplayer agents={agents} cases={[{
  ...cases[0],
  events: [{ ...cases[0].events[0], blocks: [{ ...cases[0].events[0].blocks[0], content: "" }] }],
}]} />

Theme overrides

colors supplies scoped values for these CSS variables. Values can be any CSS color value accepted by the browser.

| Key | CSS variable | | --- | --- | | background | --asr-background | | surface | --asr-surface | | border | --asr-border | | text | --asr-text | | muted | --asr-muted | | implementer | --asr-implementer | | reviewer | --asr-reviewer | | success | --asr-success | | danger | --asr-danger | | focus | --asr-focus |

<AgentSessionReplayer
  agents={agents}
  cases={cases}
  colors={{ background: "#080b12", reviewer: "#ff8a65", focus: "#8ab4f8" }}
/>

Rendering, motion, and accessibility

The package is safe to import and server-render: browser APIs and timers are accessed only in effects, so server markup and the initial client markup are deterministic. When prefers-reduced-motion: reduce is active, events complete without the typing and collapse animations.

Navigation uses labeled buttons and each expanded event is exposed as an article with its event title. Keep the supplied titles and summaries meaningful so the replay remains understandable to assistive technology.

The player always includes a quiet devos attribution link in its in-frame footer.

Bun development

This workspace uses Bun 1.3.8 and bun.lock.

bun install
bun run dev
bun run test
bun run typecheck
bun run build
bun run build:package

The root commands run the demo workspace. bun run build:package builds the embeddable package into packages/agent-session-replayer/dist.