# sushit-prog/langgraph-replay architecture

> Architecture diagram of the GitHub repository sushit-prog/langgraph-replay, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sushit-prog/langgraph-replay
- Repository: https://github.com/sushit-prog/langgraph-replay

## Overview

1. This repo is effectively two related layers: the main shipped package in `src/langgraph_replay`, and a second `agenttrace` package with similar-but-separate analysis tooling. The README and install surface point to `langgraph_replay` as the primary product; `agenttrace` looks like an experimental or adjacent codebase kept in the same repo for loop detection, counterfactual replay, annotations, and watchdog experiments.

2. The core runtime path is recording LangGraph agent execution through a LangChain callback handler. `LangGraphRecorder` / `record_session` / `arecord_session` wrap `graph.invoke(...)` or `graph.ainvoke(...)` and capture node-by-node state transitions plus LLM metadata. This is the ingestion boundary: the agent emits execution events, and the recorder turns them into persisted session data.

3. Persisted sessions are stored locally in SQLite under `~/.langgraph_replay/replays.db`. The storage layer is the main durable boundary between “runtime capture” and “offline analysis.” Everything else in the toolchain reads from that session database to list runs, show details, export/delete sessions, compute leaderboards, and replay or compare executions.

4. The analysis pipeline in `src/langgraph_replay` is split into focused modules:
   - `replay.py` reconstructs a run from recorded events.
   - `diff.py` compares sessions.
   - `blame.py` identifies the node most likely responsible for failure.
   - `diagnosis.py` adds higher-level root-cause reasoning and fix suggestions.
   - `search.py` provides semantic lookup across recorded sessions.
   - `storage.py` and `search.py` are the query backbone for all of these.

5. “Blame” has two distinct modes. Structural blame is immediate and local: it reasons from state changes and node boundaries without external calls. Semantic blame and diagnosis are optional higher-cost paths that can use model-based evaluation or explanation, which is why the README mentions `--eval`, `--baseline`, and `--diagnose`. That creates a clear boundary between deterministic replay analysis and LLM-assisted interpretation.

6. Semantic search is a separate subsystem rather than a simple text filter. The repository includes a search engine over session content, with embeddings implied by the search API and the provider leaderboard. This means the SQLite store is likely used for both structural metadata and vector/semantic lookup, while the query layer turns natural-language prompts into ranked historical sessions.

7. The regression watchdog is another major flow: `watchdog.py` and the `watch` CLI monitor an agent source file, rerun saved sessions after edits, and compare results against previous behavior. The watchdog boundary is “code changed -> replay sessions -> detect regressions -> emit report.” It is intentionally file-driven and local, aimed at catching behavior drift during development rather than in production.

8. The terminal UI is a separate presentation layer for interactive inspection. `tui/app.py` and `tui/widgets.py` provide the debug experience invoked by `langgraph-replay debug <session>`. This sits on top of the same stored sessions and replay logic, so the TUI is a view layer, not a source of truth.

9. The repo also contains a substantial `agenttrace` package with its own internal subsystems:
   - `annotations` for storing labeled execution metadata,
   - `counterfactual` for replaying alternate paths,
   - `loopdetect` for cycle finding, classification, and embeddings,
   - `watchdog` for baseline comparison, semantic diffing, upstream divergence, and reporting.
   These modules suggest a parallel analysis framework focused on detecting loops, retries, regressions, and divergence across runs.

10. Fixtures and tests are architecture-significant here because they encode the expected shapes of failures and edge cases. The various JSON fixtures for clean runs, regressed runs, missing nodes, stuck loops, retries, and upstream divergence act as canonical examples for replay, blame, diff, and watchdog behavior. The tests in `tests/` and `agenttrace/tests/` validate the boundaries between recording, storage, analysis, and reporting.

11. There are also demo and example entry points that show how the library is embedded into a real agent workflow. `examples/simple_agent.py` and `demo/research_agent.py` / `demo/run_demo.py` demonstrate the recording boundary from the agent side, while generated reports such as `demo_report.json` and `watchdog-report.json` show the downstream analysis artifacts.

12. In diagram terms, the main architecture is: LangGraph agent execution enters through a callback recorder, gets persisted to local SQLite, and is then consumed by several read-side tools—list/show/export, replay/diff, blame/diagnosis, semantic search, watchdog, and TUI debugging. Optional model-based features and embeddings introduce external service dependencies, but the core structural analysis remains local and offline.

Main entry points: [`src/langgraph_replay/storage.py`](https://github.com/sushit-prog/langgraph-replay/blob/main/src/langgraph_replay/storage.py) (Storage), [`src/langgraph_replay/cli.py`](https://github.com/sushit-prog/langgraph-replay/blob/main/src/langgraph_replay/cli.py) (CLI), [`src/langgraph_replay/watchdog.py`](https://github.com/sushit-prog/langgraph-replay/blob/main/src/langgraph_replay/watchdog.py) (Watchdog), [`agenttrace/fixtures/clean_run_fixture.json`](https://github.com/sushit-prog/langgraph-replay/blob/main/agenttrace/fixtures/clean_run_fixture.json) (Run fixtures)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_main["langgraph_replay"]
  node_n_recorder["Recorder<br/>callback ingestion<br/>[recorder.py]"]
  node_n_storage[("Storage<br/>sqlite persistence<br/>[storage.py]")]
  node_n_replay["Replay<br/>run reconstruction<br/>[replay.py]"]
  node_n_diff["Diff<br/>session comparison<br/>[diff.py]"]
  node_n_blame["Blame<br/>failure attribution<br/>[blame.py]"]
  node_n_diagnosis["Diagnosis<br/>root-cause reasoning<br/>[diagnosis.py]"]
  node_n_search["Search<br/>semantic lookup<br/>[search.py]"]
  node_n_cli["CLI<br/>command interface<br/>[cli.py]"]
  node_n_tui["TUI<br/>interactive viewer<br/>[app.py]"]
  node_n_watchdog["Watchdog<br/>regression monitor<br/>[watchdog.py]"]
end

subgraph group_grp_agenttrace["agenttrace"]
  node_n_annotations["Annotations<br/>labeled metadata<br/>[store.py]"]
  node_n_cf_replay["Counterfactual<br/>alternate replay<br/>[replay.py]"]
  node_n_loopdetect["Loop detect<br/>cycle analysis<br/>[cycle_finder.py]"]
  node_n_loop_classifier["Classifier<br/>loop classification<br/>[classifier.py]"]
  node_n_agent_watchdog["Agent watchdog<br/>baseline comparison<br/>[compare.py]"]
end

subgraph group_grp_examples["Examples & fixtures"]
  node_n_example_agent["Example agent<br/>demo workflow<br/>[simple_agent.py]"]
  node_n_demo["Research demo<br/>demo workflow<br/>[research_agent.py]"]
  node_n_fixtures["Run fixtures<br/>canonical inputs"]
end

node_n_recorder -->|"persist session"| node_n_storage
node_n_storage -->|"load run"| node_n_replay
node_n_storage -->|"compare sessions"| node_n_diff
node_n_storage -->|"analyze failure"| node_n_blame
node_n_storage -->|"explain failure"| node_n_diagnosis
node_n_storage -->|"query corpus"| node_n_search
node_n_cli -->|"record"| node_n_recorder
node_n_cli -->|"replay"| node_n_replay
node_n_cli -->|"diff"| node_n_diff
node_n_cli -->|"blame"| node_n_blame
node_n_cli -->|"diagnose"| node_n_diagnosis
node_n_cli -->|"search"| node_n_search
node_n_cli -->|"watch"| node_n_watchdog
node_n_tui -->|"inspect"| node_n_storage
node_n_watchdog -->|"rerun"| node_n_replay
node_n_watchdog -->|"regression check"| node_n_diff
node_n_watchdog -->|"baseline source"| node_n_storage
node_n_annotations -->|"label runs"| node_n_agent_watchdog
node_n_cf_replay -.->|"uses examples"| node_n_fixtures
node_n_loopdetect -->|"classify loops"| node_n_loop_classifier
node_n_agent_watchdog -->|"compare baselines"| node_n_storage
node_n_example_agent -->|"emit events"| node_n_recorder
node_n_demo -->|"emit events"| node_n_recorder
node_n_fixtures -.->|"validate replay"| node_n_replay
node_n_fixtures -.->|"validate blame"| node_n_blame
node_n_fixtures -.->|"validate regressions"| node_n_watchdog

click node_n_recorder "https://github.com/sushit-prog/langgraph-replay/blob/main/src/langgraph_replay/recorder.py"
click node_n_storage "https://github.com/sushit-prog/langgraph-replay/blob/main/src/langgraph_replay/storage.py"
click node_n_replay "https://github.com/sushit-prog/langgraph-replay/blob/main/src/langgraph_replay/replay.py"
click node_n_diff "https://github.com/sushit-prog/langgraph-replay/blob/main/src/langgraph_replay/diff.py"
click node_n_blame "https://github.com/sushit-prog/langgraph-replay/blob/main/src/langgraph_replay/blame.py"
click node_n_diagnosis "https://github.com/sushit-prog/langgraph-replay/blob/main/src/langgraph_replay/diagnosis.py"
click node_n_search "https://github.com/sushit-prog/langgraph-replay/blob/main/src/langgraph_replay/search.py"
click node_n_cli "https://github.com/sushit-prog/langgraph-replay/blob/main/src/langgraph_replay/cli.py"
click node_n_tui "https://github.com/sushit-prog/langgraph-replay/blob/main/src/langgraph_replay/tui/app.py"
click node_n_watchdog "https://github.com/sushit-prog/langgraph-replay/blob/main/src/langgraph_replay/watchdog.py"
click node_n_annotations "https://github.com/sushit-prog/langgraph-replay/blob/main/agenttrace/annotations/store.py"
click node_n_cf_replay "https://github.com/sushit-prog/langgraph-replay/blob/main/agenttrace/counterfactual/replay.py"
click node_n_loopdetect "https://github.com/sushit-prog/langgraph-replay/blob/main/agenttrace/loopdetect/cycle_finder.py"
click node_n_loop_classifier "https://github.com/sushit-prog/langgraph-replay/blob/main/agenttrace/loopdetect/classifier.py"
click node_n_agent_watchdog "https://github.com/sushit-prog/langgraph-replay/blob/main/agenttrace/watchdog/compare.py"
click node_n_example_agent "https://github.com/sushit-prog/langgraph-replay/blob/main/examples/simple_agent.py"
click node_n_demo "https://github.com/sushit-prog/langgraph-replay/blob/main/demo/research_agent.py"
click node_n_fixtures "https://github.com/sushit-prog/langgraph-replay/blob/main/agenttrace/fixtures/clean_run_fixture.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_recorder,node_n_storage,node_n_replay,node_n_diff,node_n_blame,node_n_diagnosis,node_n_search,node_n_cli,node_n_tui,node_n_watchdog toneBlue
class node_n_annotations,node_n_cf_replay,node_n_loopdetect,node_n_loop_classifier,node_n_agent_watchdog toneAmber
class node_n_example_agent,node_n_demo,node_n_fixtures toneMint
```

## Components

### langgraph_replay

Primary shipped package for recording, persistence, replay, analysis, and interactive inspection.

- [Recorder](https://github.com/sushit-prog/langgraph-replay/blob/main/src/langgraph_replay/recorder.py): callback ingestion · LangChain callback wrapper that captures LangGraph execution events and session metadata. · `src/langgraph_replay/recorder.py`
- [Storage](https://github.com/sushit-prog/langgraph-replay/blob/main/src/langgraph_replay/storage.py): sqlite persistence · Durable session store, centered on the local replay database used by read-side tools. · `src/langgraph_replay/storage.py`
- [Replay](https://github.com/sushit-prog/langgraph-replay/blob/main/src/langgraph_replay/replay.py): run reconstruction · Rebuilds recorded executions from persisted events. · `src/langgraph_replay/replay.py`
- [Diff](https://github.com/sushit-prog/langgraph-replay/blob/main/src/langgraph_replay/diff.py): session comparison · Compares sessions and highlights behavioral differences. · `src/langgraph_replay/diff.py`
- [Blame](https://github.com/sushit-prog/langgraph-replay/blob/main/src/langgraph_replay/blame.py): failure attribution · Identifies the node most likely responsible for a failure, using structural analysis first. · `src/langgraph_replay/blame.py`
- [Diagnosis](https://github.com/sushit-prog/langgraph-replay/blob/main/src/langgraph_replay/diagnosis.py): root-cause reasoning · Higher-level explanation and fix suggestion layer built on top of blame and replay outputs. · `src/langgraph_replay/diagnosis.py`
- [Search](https://github.com/sushit-prog/langgraph-replay/blob/main/src/langgraph_replay/search.py): semantic lookup · Query and ranking layer for finding relevant historical sessions. · `src/langgraph_replay/search.py`
- [CLI](https://github.com/sushit-prog/langgraph-replay/blob/main/src/langgraph_replay/cli.py): command interface · User-facing commands for record, list, show, replay, diff, blame, diagnose, search, and watch flows. · `src/langgraph_replay/cli.py`
- [TUI](https://github.com/sushit-prog/langgraph-replay/blob/main/src/langgraph_replay/tui/app.py): interactive viewer · Terminal debug interface for inspecting stored sessions and replay state. · `src/langgraph_replay/tui/app.py`
- [Watchdog](https://github.com/sushit-prog/langgraph-replay/blob/main/src/langgraph_replay/watchdog.py): regression monitor · Local watch flow that reruns saved sessions after edits and compares behavior for regressions. · `src/langgraph_replay/watchdog.py`

### agenttrace

Adjacent analysis toolkit in the same repo for annotations, counterfactual replay, loop detection, and watchdog experiments.

- [Annotations](https://github.com/sushit-prog/langgraph-replay/blob/main/agenttrace/annotations/store.py): labeled metadata · Stores execution labels and annotation metadata for analysis and review. · `agenttrace/annotations/store.py`
- [Counterfactual](https://github.com/sushit-prog/langgraph-replay/blob/main/agenttrace/counterfactual/replay.py): alternate replay · Replays alternate paths to explore what would happen under different execution choices. · `agenttrace/counterfactual/replay.py`
- [Loop detect](https://github.com/sushit-prog/langgraph-replay/blob/main/agenttrace/loopdetect/cycle_finder.py): cycle analysis · Finds and classifies cycles, with embedding support for loop-related analysis. · `agenttrace/loopdetect/cycle_finder.py`
- [Classifier](https://github.com/sushit-prog/langgraph-replay/blob/main/agenttrace/loopdetect/classifier.py): loop classification · Classifies detected loop patterns and supports semantic loop analysis. · `agenttrace/loopdetect/classifier.py`
- [Agent watchdog](https://github.com/sushit-prog/langgraph-replay/blob/main/agenttrace/watchdog/compare.py): baseline comparison · Comparative analysis, semantic diffing, upstream divergence, and report generation for agenttrace. · `agenttrace/watchdog/compare.py`

### Examples & fixtures

Demo agents, reports, and canonical run fixtures used to exercise the system.

- [Example agent](https://github.com/sushit-prog/langgraph-replay/blob/main/examples/simple_agent.py): demo workflow · Minimal LangGraph agent used to demonstrate recording and replay integration. · `examples/simple_agent.py`
- [Research demo](https://github.com/sushit-prog/langgraph-replay/blob/main/demo/research_agent.py): demo workflow · Larger demo agent and runner showing how the library is embedded in a real workflow. · `demo/research_agent.py`
- [Run fixtures](https://github.com/sushit-prog/langgraph-replay/blob/main/agenttrace/fixtures/clean_run_fixture.json): canonical inputs · Representative clean, regressed, looped, retrying, and divergence runs used by tests and demos. · `agenttrace/fixtures/clean_run_fixture.json`

## Connections

- Recorder → Storage: persist session · Recorded execution events are written to durable session storage.
- Storage → Replay: load run · Replay reconstructs executions from stored events.
- Storage → Diff: compare sessions · Diff reads multiple stored sessions to compute changes.
- Storage → Blame: analyze failure · Blame uses persisted state transitions and node boundaries.
- Storage → Diagnosis: explain failure · Diagnosis consumes stored sessions and blame results.
- Storage → Search: query corpus · Search indexes and retrieves historical sessions from storage.
- CLI → Recorder: record · CLI exposes the recording entrypoint around graph execution.
- CLI → Replay: replay · CLI launches replay of a stored session.
- CLI → Diff: diff · CLI compares sessions from the command line.
- CLI → Blame: blame · CLI surfaces failure attribution.
- CLI → Diagnosis: diagnose · CLI surfaces deeper root-cause analysis.
- CLI → Search: search · CLI provides natural-language or semantic lookup.
- CLI → Watchdog: watch · CLI starts regression monitoring and comparison.
- TUI → Storage: inspect · The TUI renders stored sessions and replay state.
- Watchdog → Replay: rerun · Watchdog replays saved sessions after source edits.
- Watchdog → Diff: regression check · Watchdog compares new behavior to prior baselines.
- Watchdog → Storage: baseline source · Watchdog relies on stored sessions as its comparison source.
- Annotations → Agent watchdog: label runs · Annotations feed labeled metadata into watchdog-style analysis.
- Counterfactual → Run fixtures: uses examples · Counterfactual replay is exercised by representative fixtures.
- Loop detect → Classifier: classify loops · Cycle detection feeds loop classification and semantic analysis.
- Agent watchdog → Storage: compare baselines · Agenttrace watchdog reads runs and baselines for divergence checks.
- Example agent → Recorder: emit events · Example workflows demonstrate the recording boundary.
- Research demo → Recorder: emit events · Demo workflows exercise recorder integration in a realistic agent.
- Run fixtures → Replay: validate replay · Canonical fixtures are used to verify reconstruction behavior.
- Run fixtures → Blame: validate blame · Fixtures encode expected failure and edge-case shapes.
- Run fixtures → Watchdog: validate regressions · Fixtures provide baseline and regressed runs for regression checks.
