rappidAI research

rappidAI Replay. Understand every run.

Replay is a local-first execution recorder and state engine for AI-agent runs. Its deterministic core works without AI and is designed to make technical execution inspectable, restorable, branchable and comparable.

GitHubADR indexReviewed revision
replay · sessionEXPERIMENTAL · CURRENT IMPLEMENTATION
  1. 01CLI / API layer
  2. 02Session + event services
  3. 03Generic recorder + adapters
  4. 04Event bus + state engine
  5. 05SQLite metadata and indexes
  6. 06Content-addressed state storage
  7. 07Optional read-only intelligence layer

Current

What is implemented today.

  • Generic execution recording with command, process and workspace capture.
  • Verification of recorded state.
  • Verified restore into a staged tree.
  • Branch creation from historical state with explicit live-rerun consent.
  • Live reruns with explicit execution consent. Recorded, controlled and hybrid modes are not implemented.
  • Deterministic multi-dimensional replay diff.

Design law

The architecture separates evidence from interpretation.

  1. 01

    The deterministic core is complete without AI.

  2. 02

    The Generic Recorder remains mandatory; adapters may enrich but never gate recording.

  3. 03

    Watcher events are triggers for reconciliation, not authoritative truth.

  4. 04

    Final checkpoints plus reconciled file events and Merkle state are the technical source of truth.

  5. 05

    Playback and re-execution are separate concepts: playback reads stored evidence, rerun executes code.

Reproducibility ladder

Reproducibility is a ladder, not a binary claim.

R0–R4 is the architecture contract for describing achieved reproducibility. The page does not claim every level is fully implemented for every session today.

  1. R0

    Inspectable

  2. R1

    Restorable

  3. R2

    Re-executable

  4. R3

    Controlled external I/O

  5. R4

    Containerized / fully captured

Architecture

State and storage architecture.

Engineering findings.

  • Reliable restore needs its own state model rather than relying only on terminal logs.
  • Content-addressed storage and recursive state trees make state identity explicit and deduplicable.
  • A filesystem watcher cannot be the source of truth by itself; reconciliation and checkpoints are required.
  • Recorded playback should never silently execute code or access the network.
  • Adapters are additive so reproducibility does not depend on one IDE or agent vendor.

Planned / Architecture target

Architecture targets that must not be confused with current implementation.

  • Portable .rplay export/import package
  • Complete external-I/O cassette ecosystem
  • Full local UI
  • Optional local intelligence sidecar
  • Broader adapter coverage and hardening

Current CLI surface.

rappid replay
rappid replay record -- <command>
rappid replay verify <state-id>
rappid replay restore <state-id>
rappid replay branch <state-id>
rappid replay rerun --mode live --confirm-execution <state-id> -- <command>
rappid replay diff <left-session-id> <right-session-id>

Who it is for.

Developers and researchers debugging autonomous agents, comparing execution paths, reproducing failures, testing agent changes and preserving inspectable local evidence of what a run changed.

Reviewed architecture and source

Pinned READMERestore ADRBranch/Rerun ADRDiff ADR