Reelier

Agents make claims. Reelier writes receipts.

Record the run that worked, replay it deterministically — 0 tokens, byte-identical, a receipt on every step — and reelier diff catches the day it drifts.

Think of it as CI + snapshot tests for your agent's tool-call workflows.

Website · Docs · SPEC.md

▶ watch with sound (22s)

Your agent re-derives the same workflow every run — burning tokens and quietly drifting. Reelier compiles a run that worked into a SKILL.md file that replays deterministically (no LLM, 0 tokens, every step asserted into a receipt), then diffs runs to catch the day it stops matching. For agents on recurring production workflows — where "it ran" isn't proof.

Install → your first receipt in 60 seconds

npm i -g reelier && reelier init

reelier init scans the work you've already done first — across Claude Code, Codex, Windsurf, and OpenClaw — and offers to turn a real past session into a replayable skill. No such history? It runs a zero-setup demo and closes with a real receipt:

Your receipt:
  skill:        reelier-init-demo
  steps:        2 total, 2 passed, 0 unchecked, 0 failed
  replay time:  44ms  [measured]
  LLM tokens:   0     [measured]

  An agent doing a comparable task re-reasons every run (~2.8s, ~18k tokens on
  our benchmark). Your replay: 44ms, 0 tokens.

Or run it with Docker — no Node install

docker run --rm ghcr.io/seldonframe/reelier --help

# Replay a skill from the current directory:
docker run --rm -v "$PWD:/work" -w /work ghcr.io/seldonframe/reelier run my.skill.md

# Record from your agent history (mount it read-only):
docker run --rm -v "$HOME/.claude:/root/.claude:ro" -v "$PWD:/work" -w /work \
  ghcr.io/seldonframe/reelier scan

Why

• Your agent relearns the job every run — then quietly drifts. Every run re-derives the workflow, and every small "rational" fix compounds — what long-run operators call scar tissue. A compiled skill never relearns and can't drift.

• The real problem is the bill. "How much did that cost?" is the first reply every long agent run gets. Reelier replays for 0 tokens, with a receipt.

• It's not brittle RPA. Replays tool calls (typed JSON in/out), not pixels — and every step carries its own assertion, so a broken step fails loudly, never silently passes.

• Upgraded the model? A replay is pinned — re-record on the new model and reelier diff against your frozen baseline: SAME or DRIFTED, per step, before it reaches production.

• "Anything deterministic should just be code." Agreed — your agent already wrote it. Reelier captures its real, working run into a tested file. Determinism without the hand-coding.

How it works — record → compile → replay → diff → receipt

reelier init                        # 60s: record → compile → replay → your receipt
reelier run  <name>.skill.md        # replay deterministically — 0 tokens (read-only by default)
reelier diff <name>                 # SAME or DRIFTED, per step — exit 1 on drift
reelier push <name>.skill.md        # sync receipts to your ledger (opt-in)

1. Record — three ways: reelier mcp --wrap "<your mcp server>" (a lossless proxy in front of your agent's tools), straight from an existing session (reelier scan / reelier from-session), or the guided reelier init.

2. Compile — reelier compile turns a trace into a SKILL.md deterministically (0 LLM calls) — a recipe with an assertion on every step, and the compiler's honest gaps printed as Open questions (including literal dates, UUIDs, and timestamps it flags as "should this be a variable?") rather than guessed at.

3. Replay — reelier run runs it at Level 0: no LLM, milliseconds, byte-identical. Read-only by default — a write step (idempotent-write) never re-fires unless you pass --allow-writes.

4. Diff — reelier diff compares two runs of a skill and reports SAME or DRIFTED per step, with the failing assertion as the why. Exit code 1 on drift, so it gates a scheduled replay.

5. Receipt — every run is a receipt (per-step outcomes, timing, 0 tokens). reelier push optionally syncs them to a receipt ledger for a shareable permalink + an embeddable verified-replay badge.

Convert an Agent Skill

Turn an instruction skill + one recorded run into a deterministic replay — your skill, minus the model:

reelier mcp --wrap "<your mcp server>"                 # record: agent runs the skill's task once
reelier compile trace.jsonl --from-skill ./my-skill/SKILL.md
# → my-skill.skill.md — name + description carried from your SKILL.md,
#   steps ONLY from the recorded run (never generated from instruction text)

Import sessions from any agent

You already have replayable workflows sitting in your agent's own session logs. reelier scan finds them; reelier from-session turns one into a skill. Format is sniffed from the file's content — no flag needed for the supported agents:

reelier scan                                          # discovers sessions from every known agent under your home dir
reelier from-session ~/.claude/projects/*/*.jsonl      # Claude Code
reelier from-session ~/.codex/sessions/**/rollout-*.jsonl   # Codex CLI
reelier from-session ~/.openclaw/agents/*/sessions/*.jsonl  # OpenClaw

Only replayable calls (Reelier's own builtins, or mcp__<server>__<tool> calls) ever compile into a skill — native file/shell/search actions are reported as skipped, never fabricated into a step. Pass --agent <claude-code|codex|openclaw> to force a format instead of auto-detecting; reelier scan / reelier from-session --agent cursor (or --agent windsurf) report what's on disk honestly rather than guessing at an undocumented binary format.

Three tests, one skill

One recorded skill gives you three different questions to ask of it, not one:

• Determinism — reelier run <skill.md> replays against the assertions you recorded. Same steps, same asserts, 0 tokens. Answers: does this still do what it did?

• Recovery — reelier run <skill.md> --fail N[=status] injects a synthetic failure at step N (default status 500; override with --fail N=429, repeatable) instead of dispatching that step's real tool call, then runs the SAME escalation ladder a real failure would hit. Nothing outside the network actually happens — a mocked step never calls its tool, so you can recovery-test a write step with no --allow-writes and no side effect. Answers: if this broke, would the skill notice and heal? (A mock run is a local test only — reelier push refuses to publish one; see below.)

• Drift — reelier run <skill.md> --wrap "<your mcp server>" replays against your live, read-only dependencies instead of the recorded trace. Paired with reelier manifest (below), this is how you catch a tool's schema moving out from under you before a real replay does.

Taxonomy due to Mads Hansen's review of the launch post.

Tool-schema drift: reelier manifest

A skill's steps call specific tools with specific argument shapes. If a wrapped MCP server's tool schema changes since you recorded against it, replay should refuse loudly, not silently fill the wrong args. reelier manifest stamps a schema digest for every tool the skill's steps actually use:

reelier manifest <skill.md> --wrap "<your mcp server>"   # stamp/refresh the manifest from live servers
reelier run <skill.md> --wrap "<your mcp server>"         # preflight checks the manifest BEFORE step 1 runs

If a stamped tool's schema has drifted (or the tool is gone), reelier run fails closed — MANIFEST DRIFT — refusing to replay — before anything executes. --ignore-manifest is the explicit break-glass override for when you know the drift is fine; it's still recorded on the run (manifestIgnored: true), so it's never a silent bypass. A skill with no manifest at all just gets an advisory note — every pre-manifest skill keeps working unmodified.

Per-step write approval: reelier approve

--allow-writes/--yes are blanket flags — they say "this run may write," not "this exact write is reviewed." reelier approve hash-binds approval to one specific step's tool + argument template:

reelier approve <skill.md>          # walk each write/destructive step, y/N to approve
reelier approve <skill.md> --all    # approve every write step non-interactively

An approved step whose tool/args still match its stamped hash executes with no flags at all. If the step's tool or args have changed since approval, replay fails closed — Approval mismatch — and no flag overrides it; you re-review and re-approve. A write step with no approve: field keeps today's exact --allow-writes/--yes behavior, unchanged.

Assert the value, not just the shape

A skill's assertions are what make a replay proof. The grammar checks status, structure, and value:

- assert: status == 200
- assert: json.results is array
- assert: json.count >= 1              # numeric range
- assert: json.plan is string          # type
- assert: json.id matches /^usr_/      # value pattern
- assert: body contains "ok"

Use it inside your coding agent (MCP)

reelier serve exposes Reelier's own commands as MCP tools, so Claude Code / Cursor / Windsurf / Codex can call it mid-session:

{ "mcpServers": { "reelier": { "command": "npx", "args": ["-y", "reelier", "serve"] } } }

The agent gets reelier_scan, reelier_from_session, reelier_replay, reelier_diff, and reelier_push — with descriptions that tell it exactly when to use each (and when not to). It records a deterministic task once, then replays instead of re-reasoning.

Tools

• reelier_scan — scan agent session history (Claude Code, Codex, Windsurf, OpenClaw) for replayable tool-call workflows

• reelier_from_session — compile a recorded session into a replayable SKILL.md with an assertion on every step

• reelier_replay — replay a skill deterministically at 0 LLM tokens (read-only by default; writes gated behind --allow-writes)

• reelier_diff — compare two runs: SAME or DRIFTED per step, with the failing assertion as the why; exit 1 on drift

• reelier_push — sync a run receipt to the ledger for a shareable permalink (opt-in)

The measured proof

From a real, live head-to-head benchmark (agent vs. Reelier, same task, same data) — full tables + methodology in examples/benchmark:

• 1,000 / 1,000 replays byte-identical (N=1000 tail-variance test)

• 0 tokens per replay — verified from the run record, not assumed

• ~50× cheaper ($0.000000/replay vs. $0.019068/run averaged over the agent arm)

• ~59× faster (48ms vs. 2,842ms average latency)

• a real drift self-healed for ~$0.001, once, then free every replay after

Latency varies by network — Level-0 replay re-executes the skill's tool calls, so wall-clock depends on your connection. What does not vary: 0 LLM tokens, the same steps every run, and the receipt. Independently corroborated — arXiv 2605.14237 found 93.3–99.98% token reduction for the same record-and-replay pattern.

Works with any model (BYOK)

Level-0 replay (the default) never calls a model — 0 tokens, by construction. Escalation (--max-level 1|2) is opt-in and speaks through one narrow BYOK surface (--llm-base-url + --llm-model): a native Anthropic Messages adapter, and an OpenAI-compatible adapter for everything else (OpenRouter, Ollama, Gemini's OpenAI endpoint, Groq, vLLM, LM Studio, Kimi, …). Point it at a stronger model and every skill's next self-heal gets smarter for free.

Own it — MIT, BYOK, local-first

Use it anywhere, embed it in anything — no copyleft strings, no legal review needed. Your skills, traces, and run records are your data — leaving is copying a folder. The formats are specified in SPEC.md, a normative RFC-style reference so anyone can emit or consume them without reading the source.

Contributing

Issues and PRs welcome — see SPEC.md for the formats (the spec wins over the code; fix the code, not the spec). npm test runs the full suite; npm run build && npx tsc --noEmit before a PR.

git clone https://github.com/seldonframe/reelier && cd reelier
npm install && npm test

Star history

License

MIT — free to fork, embed, audit, and self-host forever. (Versions ≤0.16.0 were released under AGPL-3.0 and remain so.)

If Reelier saved you a re-run, star it ⭐ — it's how other builders find it.