# Record a Claude Code run once. Replay it at 0 tokens.

> Your session history is already full of jobs that never needed a second reasoning pass. Freeze one into a SKILL.md, replay it deterministically, and read the receipt.

Markdown twin of https://www.reelier.com/for/claude-code — deterministic replay for Claude Code. Reelier records what an agent actually did, compiles it into a SKILL.md with minimal per-step assertions, and replays it at 0 LLM tokens with a receipt every run.

## How capture works on Claude Code

Claude Code writes every session as a JSONL transcript, and that format is the one `reelier scan` parses natively. Scan reads your history, lists the sessions with a replayable tool-call core, and `reelier from-session` freezes one into a SKILL.md with minimal per-step assertions. The work is already paid for; freezing it costs nothing.

For runs you haven't done yet, `reelier install` turns on lossless capture: it fronts every local MCP server in your config with the `reelier mcp --wrap` recording proxy, backing the config up first. Wrap captures lossless traces (tool annotations included) — scan-from-history is a reconstruction; wrap is the recording.

`reelier scan` reads: `~/.claude/projects`
(The literal directory scan reads for Claude Code (reelier/src/scan.ts). Missing dirs are skipped silently; sessions sort by recency.)

## Wire it up

### .mcp.json — Reelier's tools inside Claude Code

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

Or one command: `claude mcp add reelier -- npx -y reelier serve`. `reelier serve` exposes `reelier_scan`, `reelier_from_session`, `reelier_replay`, `reelier_diff` and `reelier_push` as MCP tools, so the agent can freeze and replay mid-session.

### terminal — teach Claude Code when to replay

```sh
mkdir -p ~/.claude/skills/reelier
curl -fsSL https://raw.githubusercontent.com/seldonframe/reelier/main/integrations/claude-code/reelier/SKILL.md \
  -o ~/.claude/skills/reelier/SKILL.md
```

Project-level works too: `.claude/skills/reelier/SKILL.md`. The skill's rules: replay before redoing a job, compile only from a run that actually happened, never report an unseen pass.

### terminal — lossless capture, one command

```sh
npx -y reelier install
# wraps every local MCP server in .mcp.json / ~/.claude.json;
# your config is backed up first. Revert anytime:
npx -y reelier uninstall
```

Claude Code is the one agent with one-command install today (`--agent claude`, the only supported value). On other agents you wrap the config entry by hand — each platform page shows the exact shape.

### .github/workflows/reelier.yml — gate CI on the recorded skill

```yaml
name: Reelier replay
on:
  pull_request:
    paths: ["my-job.skill.md"]   # gate only when the skill changes
  schedule:
    - cron: "0 8 * * *"          # daily, UTC — a standing dated proof
jobs:
  replay:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: seldonframe/reelier@v1
        with:
          skill: my-job.skill.md
          max-level: "0"          # 0 LLM tokens — pure deterministic replay
          cloud-key: ${{ secrets.REELIER_CLOUD_KEY }}  # optional receipt push
```

Freeze a session into `my-job.skill.md` (steps below), commit it, and the `seldonframe/reelier@v1` action re-runs it on every PR that touches it: it installs `reelier@^0.12`, runs `reelier run my-job.skill.md --max-level 0`, posts the receipt as a job summary, and fails the check on the run's exit code. At `max-level: "0"` the replay never calls a model, so a green check costs 0 tokens and a step whose assertion no longer holds turns the build red. Full CI setup: /for/github-actions.

## First receipt in 60 seconds

1. `npm i -g reelier` — Install the CLI — or run every command below through `npx -y reelier`.
2. `reelier scan` — List replayable tool-call sequences from `~/.claude/projects` — your history, already paid for.
3. `reelier from-session <transcript.jsonl> --name my-job` — Freeze the session's tool calls into `my-job.skill.md`, with minimal per-step assertions.
4. `reelier run my-job.skill.md` — Deterministic replay: 0 LLM tokens, per-step pass/fail, a receipt in `.reelier/runs/`. From the second run on, `reelier diff my-job` gates drift — exit 1 when something real changed.

Prefer a guided path? `npx -y reelier init` walks record → compile → replay in about 60 seconds.

## A real receipt

Verbatim output of a portfolio replay, run 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). The run record confirms passed: true and 0 LLM tokens. Replay it yourself:

```
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
```

## FAQ

**Does replay call a model?**

No. `reelier run` executes the recorded tool calls — typed JSON in, typed JSON out — and checks each recorded assertion. The 0-token figure is read off the run record, not estimated.

**What can't Reelier replay?**

Reelier replays deterministic tool calls: MCP tool calls and its own `http.get`/`http.post` builtins. It cannot replay file edits, shell commands, reads and searches, subagent dispatch, or anything non-deterministic. An edit-heavy coding session honestly reports nothing replayable — an empty result, not an error.

**reelier scan found nothing replayable — is that a bug?**

No — honest degradation. Sessions that are mostly edits, greps and shell have no replayable core, and scan says so rather than guessing. Freeze the sessions that were a sequence of API/MCP calls: data pulls, status checks, report generation, CRUD sequences.

**Can I gate my CI on agent drift?**

Yes — that's what the `.github/workflows/reelier.yml` block above does. Commit the frozen `my-job.skill.md`, and the `seldonframe/reelier@v1` action runs `reelier run` on every PR that touches it: a step whose recorded assertion no longer holds fails, `reelier run` exits non-zero, and the check turns red. The action fails the job on that exit code, so a drifted tool call blocks the merge. Full setup, inputs and outputs: /for/github-actions.

→ [Run a recorded skill as a CI gate](https://www.reelier.com/for/github-actions)

**Does the CI replay cost tokens?**

Not at `max-level: "0"` — the action's default. At level 0 `reelier run` never constructs or calls a model, so the deterministic replay of MCP and tool-call steps is 0 LLM tokens; a green check costs nothing per run. Raising max-level to 1 or 2 turns on opt-in self-healing that does need BYOK LLM credentials in the runner. Note that only the deterministic core replays — Bash, Read, Edit, Write and Grep steps are not replayed and stay unchecked.

## Links

- [Your OpenClaw cron burns 2,880 LLM calls a month. Here's the same job at zero.](https://www.reelier.com/blog/openclaw-cron-costs)
- [Scheduled agents re-learn the job every run. Replay the part that never changes.](https://www.reelier.com/blog/scheduled-agents-zero-token)
- [Agent cost calculator — what re-reasoning a recurring job costs, with your numbers.](https://www.reelier.com/tools/agent-cost-calculator)
- [seldonframe/reelier — the engine, MIT. Fork it, audit it, self-host it.](https://github.com/seldonframe/reelier)

Other agents: [Cursor](https://www.reelier.com/for/cursor) · [Codex](https://www.reelier.com/for/codex) · [Windsurf](https://www.reelier.com/for/windsurf) · [OpenClaw](https://www.reelier.com/for/openclaw) · [Hermes](https://www.reelier.com/for/hermes) · [GitHub Actions](https://www.reelier.com/for/github-actions)