Deterministic replay
Deterministic replay is the practice of re-running an AI agent's recorded work without re-running the model. The tool calls the agent made the first time — typed JSON requests and typed JSON responses — are captured, compiled into a repeatable skill file, and executed again exactly as recorded, with an assertion checking every step. Because the replay never consults an LLM, it costs zero tokens, finishes in tool-call time instead of reasoning time, and behaves the same way on every run; anything that diverges fails an assertion loudly instead of being papered over by fresh model output.
Why replay instead of re-reason
A recurring agent job re-derives the same plan on every run. The model reads the prompt, reasons its way to the same three tool calls it made yesterday, and bills you for the trip. But the output of all that reasoning is a tool-call sequence, and a tool-call sequence is data: it can be recorded once and executed again directly.
That is the whole idea. The first run is the recording. Every run after it executes the recorded calls — typed JSON in, typed JSON out — and checks an assertion on each step. No prompt, no context window, no sampling. When the receipt says 0 LLM tokens, it is because none were spent, not because someone rounded down.
You will meet the same idea under adjacent names: replayable agent runs and event-sourced execution. Same shape either way — persist what the agent actually did as data, then treat re-execution as a mechanical step rather than a fresh act of judgment.
Three senses of “replay”, one disambiguation
The term is older than agents. In systems research, deterministic replay means record/replay debugging: capture a program's nondeterministic inputs so the exact execution can be re-run under a debugger — the rr project is the canonical tool. Observability platforms use “session replay” differently again: a viewable trace of what an agent did, which you watch; nothing re-executes.
The agent-engineering sense — the one that now dominates search results and the one this page defines — sits between them: re-executing an agent's recorded tool calls against the live systems they originally hit, with assertions standing in for the model's judgment about whether each step worked. You get the debugging sense's repeatability and the trace's honesty, plus a pass/fail answer.
The boundary: what replay covers, what it refuses
Deterministic replay covers the deterministic core of a job — in Reelier's case, MCP tool calls and its own http.get/http.post builtins. It does not cover judgment. Triaging an anomaly, writing prose, deciding what to do about a change: those need a model every time, and a replay tool that pretends otherwise is lying to you. In Reelier, model help during replay is opt-in and BYOK, in levels: at the default --max-level 0 an LLM client is never even constructed; L1 may re-read an already-captured observation to heal a stale assertion; L2 may additionally re-execute a single read or idempotent-write step. Destructive steps are never escalated.
Writes get the same discipline. Replay is read-only by default: recorded write steps do not re-fire unless you pass --allow-writes. This matters more than it first appears — in the measured corpus behind Reelier's own launch writing, only 1.1% of scanned sessions were read-only end-to-end. Almost every useful agent job writes something somewhere, so a replay tool's write policy is not a footnote; it is most of the safety story.
How it works in practice
Capture comes first. Where the agent platform keeps a scannable history, reelier scan reads it directly — Claude Code's ~/.claude/projects transcripts are the native format. Where there is no scannable history (Cursor stores its history in a SQLite database, so there is no history scan for it), the recording proxy reelier mcp --wrap fronts the MCP server and records every call losslessly while the job runs once as usual.
Then the recording becomes a file: reelier from-session (from a scanned transcript) or reelier compile (from a recorded trace) emits a SKILL.md with assertions on every step it can check — steps with no meaningful assertion are surfaced as open questions and replay as unchecked, never passed. The result is a markdown artifact you read, edit, and commit to git like any other code.
Replay is reelier run my-job.skill.md: each recorded call re-executes, each assertion is checked, and a receipt lands in .reelier/runs/ with per-step outcomes, timing, and the measured token count. From the second run on, reelier diff my-job compares runs and exits 1 when something real changed — which is how a replay becomes a drift gate in cron or CI.
A real receipt
The output below is a real replay receipt, not a mockup: the registry-latest portfolio skill — one recorded HTTP call to the npm registry, two assertions — replayed on 2026-07-21 with the CLI pinned to the version that recorded the seed (npx -y reelier@0.12.1), so it reproduces verbatim. No model was in the loop at any point.
npx -y reelier@0.12.1 run examples/portfolio/registry-latest.skill.md === registry-latest === ✓ Step 1 — Latest dist-tag from the registry [passed] 152ms PASSED: 1/1 steps ok, 0 failed, 152ms total
Verbatim seed receipt recorded in seldonframe/reelier examples/portfolio/README.md (reelier@0.12.1, 2026-07-21). Replay it yourself from a checkout of the repo — read-only, no account, no key.
FAQ
Is deterministic replay just caching?
No. A cache returns the stored answer without touching the world again. A replay re-executes the recorded calls against the live systems, asserts on the fresh responses, and binds the fresh values during the run — the npm download count checked in a replayed skill is this week's number, not the recorded one. It is a re-run with the reasoning removed, not a memo of the old result.
What happens when the world changes under the recording?
The assertion on the affected step fails and the run says so — a named failing step on the receipt, reelier diff exiting 1 with the failing assertion as the why. Loud failure is the contract: a drifted step is exactly the moment judgment is worth paying for, so that is when you bring the model back, re-record, and let the next replay run at zero again.