Orcareplay

OrcaReplay

English · 简体中文 · 日本語 · 한국어 · Deutsch · Français · Español · العربية

Your agent broke something at 2am. Replay it at 9am — exactly, offline, as many times as you like.

Record any coding agent. Reproduce the run byte-for-byte with no model called. Fork it from any step onto a different model and see who gets it right.

Built by the team behind [OrcaRouter](https://www.orcarouter.ai) — one API key and one endpoint for Claude, GPT, Gemini, Grok, DeepSeek, Qwen and the rest. It is what orca setup points at by default, and what makes orca compare a single command instead of four provider accounts.

Find us: OrcaRouter All model APIs

Github Repos: OrcaCode Review · OrcaRouter Lite

Connect: X · Discord · Hugging Face · Ollama

Real output from one session — a Claude Code run recorded, replayed against the recording, then forked at checkpoint 4 onto two models and graded by npx tsc --noEmit. Nothing here is mocked up.

Try it in three commands

One npm package named orcareplay, which puts one command named orca on your PATH. There is no separate tool called "orca", and nothing is installed into your agent.

npm i -g orcareplay             # the package is orcareplay; the command it installs is orca

orca record claude # your agent, unmodified, doing whatever it does orca replay last # the same run again — no network, no tokens, no charge orca replay last --from 4 --model claude-haiku-4-5 --ui

The third line is the one people stay for: same files, same conversation prefix, different model from step 4 onward. The model is the only variable, which is what makes the answer mean anything.

The three commands at the top need an agent installed, a key, a network and real tokens. If you have none of those yet, one command brings its own:

orca quickstart

It writes a small project with a genuine bug in it and a recording of an agent fixing that bug, then replays the recording against the project with no model called: two failing tests before, four passing after, three turns served from the trace and nothing spent. --full prints the whole timeline and the replay as it happened.

Read your agent's own system prompt

A proxy that sees the whole loop also sees the prompt the harness assembled before it sent anything. One command captures it, scrubs the machine out of it, and files it by model:

node capture/capture.mjs claude --model claude-opus-5

Interactive prompts and -p prompts are not the same prompt, and neither is the same across models. See capture/README.md for the measured differences, the pitfalls, and the sanitising rules.

Why this exists

Agent debugging today is archaeology. You scroll a terminal, you re-run and get a different failure, you add print statements to someone else's harness. The tools that exist are observability tools: they tell you a run cost $4.12 and used 61k tokens, which is not the question you have. The question you have is *why did it delete my migration file.*

OrcaReplay answers that by giving you the run back.

The last two rows are the ones an SDK wrapper structurally cannot reach. Capture happens *below* the agent — at the process and socket boundary — so it does not matter whether the agent is yours, whether you can edit it, or whether it even holds an API key: a Codex CLI signed in with a ChatGPT subscription talks to its own backend over TLS, with a credential that only that backend accepts, so it cannot be pointed elsewhere and stay the same session — and orca can still record it. See when the harness will not be redirected.

How it works

Model APIs are stateless, so on every turn an agent resends the entire conversation — including the previous turn's tool results. A proxy in front of the model therefore sees the whole loop: each request, each streamed response, every tool call the model emitted, and every tool result the harness produced. That one property is what the tool is built on, and it is why OrcaReplay does not patch your agent — it stands up a local proxy, sets two environment variables, and gets out of the way.

What "egress blocked" means, exactly. On replay the proxy refuses to forward anything it cannot serve from the trace, so no model is called and no tokens are spent — that run prints egress=blocked. --loose lifts it deliberately: an unmatched request is then answered by the provider and recorded as a major divergence, and the same line reads egress=live-on-unmatched. A replay still *executes the recorded tool calls for real*, and a tool that opens its own socket — a shell command running curl, an MCP server fetching something — is outside the guarantee either way. By default it never reaches the proxy and goes to the network as usual. Under --tls-intercept it does reach the proxy, because that sets HTTPS_PROXY for the whole child: a host off the intercept list is tunnelled through untouched, though its hostname, port and byte counts still land in the trace, and a host on the list is refused there like any other unmatched call. Replay is not a sandbox; if you need one, run it inside one.

Three more layers catch what the protocol cannot see: an exit code, a real duration, which stream a byte came out of, a file written without telling anyone. A fifth exists for the agents that read no base-URL variable at all — see which agents. A sixth reads the agent's own account of its structure, for a harness that has one: which sub-agent ran, which handed off to which, whether a guardrail tripped, which graph node produced what and which of them called no model at all — none of which reaches the wire.

%%{init: {'theme':'neutral'}}%%

flowchart LR A[" your agent unmodified "]

subgraph orca["orca · six capture layers"] direction TB P[" proxy base-URL env var"] SH[" PATH shim exit code · timing · streams"] MC[" JSON-RPC tee MCP config rewrite"] FS[" shadow git index workspace per turn"] FH[" fetch hook for a hardcoded origin"] end

A --> P & SH & MC & FS & FH P -->|"forwarded, auth intact"| U[" the model API or OrcaRouter · any gateway "] orca ==> T[(" one trace .orca/runs/run_a1b2c3")]

They all land in the same timeline, ordered by when they actually happened rather than when orca got around to reading them.

Exact, fork and compare are one thing

They are not three subsystems. They are the same proxy with a cursor — the position in the recorded stream where it stops answering from disk and starts answering from the network.

%%{init: {'theme':'neutral'}}%%

flowchart LR subgraph disk["from disk · byte-for-byte · network blocked"] direction LR T1["turn 1"] --> T2["turn 2"] --> T3["turn 3"] --> T4["turn 4"] end T4 ==> CUR{{" cursor "}} CUR ==> T5 subgraph net["from the network · any model you name"] direction LR T5["turn 5"] --> T6["turn 6"] --> T7["…"] end

A checkpoint is not recorded; it is *derived* — any point where the conversation prefix is complete and the workspace was snapshotted. Every fork therefore starts from a state that provably existed.

What a bug hunt actually looks like

Your agent was supposed to fix a failing auth test. It exited 0 and the test still fails. Start with what it actually did:

$ orca show last

run_6473f858b59e generic-openai@0.1.0 14 events exit 0

SEQ KIND WHAT DETAIL 0 RUN run started generic-openai 1 SNAP tree 919d32ba037537b43814c83779963b2cc3023db7 0 changed 2 MODEL claude-opus-5 1 messages 3 MODEL claude-opus-5 stop: tool_use · 100 in · 20 out 4 TOOL edit_file {"path":"auth.ts",…} 5 SNAP tree c6af62b75c0c8b8938bd6087328b5148f3dcd534 1 changed 6 FILE auth.ts modified +1 −3 7 TOOL edit_file ok 8 MODEL claude-opus-5 3 messages 9 MODEL claude-opus-5 stop: end_turn · 101 in · 5 out 10 SNAP tree c6af62b75c0c8b8938bd6087328b5148f3dcd534 0 changed 11 SHELL ["sh","-c","node --check nonexistent-file.ts"] /tmp/hunt 12 SHELL shell result exit 1 · 43ms 13 RUN run ended exit 0

info usage input=201 output=25 cost=$0.004890

Three facts the model's own transcript could not have told you, and the run's exit code hid: the file really changed (seq 6, +1 −3), the check the agent ran failed (seq 12, exit 1), and it finished anyway. The run exited 0 because the *agent* exited 0.

That last fact is the one worth a command of its own. orca show gives you the order things happened in; orca graph gives you what produced what:

$ orca graph last

FROM TO KIND WHY 3 model.response 4 tool.call recorded tool_use block in the response 4 tool.call 6 fs.change inferred changed path appears in tool input, same or previous turn 4 tool.call 7 tool.result recorded tool result answers its call 7 tool.resu