# Deterministic replay for Windsurf workflows.

> Add Reelier to Windsurf's MCP config, record the job once through the wrap proxy, and replay it at 0 tokens with a receipt that names every asserted step.

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

## How capture works on Windsurf

`reelier scan` includes Windsurf's directory in its source list. Honest caveat: today, transcripts that don't match the Claude-style JSONL schema parse to 0 replayable sessions — scan skips what it doesn't recognize rather than inventing steps. Note that `.windsurfrules` is config, not history: scan never treats a rules file as a transcript.

The dependable capture path is the recording proxy: front the MCP server(s) your workflow uses with `reelier mcp --wrap`, run the job once in Windsurf, and the full trace lands in `.reelier/traces/`. Wrap captures lossless traces (tool annotations included) — scan-from-history is a reconstruction; wrap is the recording.

`reelier scan` reads: `~/.codeium/windsurf`
(The literal directory scan reads for Windsurf (reelier/src/scan.ts). Unrecognized transcript formats contribute 0 replayable sessions — honest degradation, never a crash.)

## Wire it up

### mcp_config.json — Reelier's tools inside Windsurf

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

Windsurf Settings → MCP Servers, or `~/.codeium/windsurf/mcp_config.json` depending on version — same `mcpServers` shape either way.

### terminal — Windsurf rules

```sh
curl -fsSL https://raw.githubusercontent.com/seldonframe/reelier/main/integrations/windsurf/reelier.md
```

Paste the output into your global Windsurf rules or a project `.windsurfrules` file — the when-to-replay guidance in Windsurf's rules format.

### mcp_config.json — record through the proxy

```json
{
  "mcpServers": {
    "your-data-server": {
      "command": "npx",
      "args": ["-y", "reelier", "mcp", "--wrap", "npx -y @yourco/mcp-server"]
    }
  }
}
```

The recorder: a lossless pass-through proxy writing `.reelier/traces/*.jsonl`. Only local stdio servers can be wrapped; http/sse entries are reported as skipped.

## First receipt in 60 seconds

1. Front your data server with the wrapped entry above and restart Windsurf.
2. Run the job once in Windsurf, as usual. The proxy records every tool call to `.reelier/traces/<name>.jsonl`.
3. `npx -y reelier compile .reelier/traces/<name>.jsonl -o my-job.skill.md` — Compile the trace into a skill — one assertion per step.
4. `npx -y reelier run my-job.skill.md` — Replay deterministically: 0 LLM tokens, receipt written. `npx -y reelier diff my-job` gates drift from the second run on.

## A real receipt

Verbatim output of a portfolio replay, run with the published CLI (`npx -y reelier@latest`, resolved to reelier@0.12.1) on 2026-07-21. The run record confirms passed: true and 0 LLM tokens. Replay it yourself:

```
npx -y reelier@latest 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 scan read .windsurfrules?**

No — deliberately. `.windsurfrules` (like `.cursor/rules`) is configuration, not a tool-call transcript, so it can't be replayed and scan doesn't pretend otherwise. Scan reads transcript directories; rules files teach the agent when to reach for replay.

**Can the replay run outside Windsurf?**

Yes — that's the point. The skill is a markdown file; `npx -y reelier run` replays it from any shell, cron job, or CI runner at 0 tokens, read-only by default.

**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.

## 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, AGPL-3.0. Fork it, audit it, self-host it.](https://github.com/seldonframe/reelier)

Other agents: [Claude Code](https://www.reelier.com/for/claude-code) · [Cursor](https://www.reelier.com/for/cursor) · [Codex](https://www.reelier.com/for/codex) · [OpenClaw](https://www.reelier.com/for/openclaw) · [Hermes](https://www.reelier.com/for/hermes)