orca-replay

OrcaReplay Run Reader

Coding agents are confidently wrong about their own history. A summary written from memory is

missing the tool results, the exit codes, and the files that changed without anyone mentioning

them.

This skill enforces one rule: **when a question is about something that already happened, read the

trace before answering.** Do not reconstruct it. If a recording exists, guessing is the wrong move

even when the guess would have been right.

When to Use This Skill

• "Why did you delete / overwrite / move X?"
• "What changed this file?" or "Which step broke the build?"
• "Can you reproduce yesterday's failure?"
• "Would a different model have got this right?"

What This Skill Does

1. Finds the run — orca_list_runs, newest first, naming the run each fork came from.
2. Narrows to the cause — orca_graph with to: <event seq> returns only the chain that

produced one event. That is the shape of an answer to why; the full timeline

(orca_show_run) is the shape of an answer to what.

1. Separates evidence from inference — every edge is labelled recorded (the recorder watched

it happen) or inferred (derived just now from a named rule). "The trace shows the rm at step

14 removed it" and "this looks like the rm at step 14, going by timing" are different claims,

and collapsing them into one confident sentence is the exact failure this skill exists to

prevent.

1. Reproduces before explaining — orca_replay re-runs the recording offline and reports what

could not be reproduced.

1. Compares models only when asked — orca_compare forks one run onto several models from the

same checkpoint, graded by a shell command whose exit code is the verdict.

How to Use

Basic Usage

Why did the last run overwrite src/config.ts?

The agent reads the trace instead of recalling the session, and answers from the tool call that

did it.

Does yesterday's failure still reproduce?

Example

User: "Which step broke the build?"

Output:

Step 14 did. From the recording (recorded edge, not inferred):

  14  TOOL   file_editor   {"command":"str_replace","path":".../tsconfig.json"}
  15  SHELL  npm run build  exit 2
  16  FILE   tsconfig.json  modified +1 -1

The edit at 14 removed "strict": true, and the build at 15 exited 2. I replayed the run
(reused=5/5, divergences=0) and it fails the same way.

Tips

• Pass worktree: true to replay. Without it, replay restores the recorded filesystem over the

working tree for the duration of the run, so uncommitted work is absent in the meantime — and

stays absent if the replay is interrupted.

• Check what re-executes before the first replay. Replay serves the model's answers from the

trace, but the agent process runs again for real, so its shell commands run again too. A run that

only read files and edited the repository is free to replay; one that touched Docker, a database

or a remote host is not.

• Replay is not a sandbox. It blocks provider egress, not the network.
• A matching replay is not a determinism result. The model is not re-asked, its recorded

answers are served back — so replay cannot tell you whether a fresh run would fail the same

way. Say so rather than implying it did.

• reused=3/5 is usually not a failure. Harnesses make calls for themselves — a quota probe, a

session-naming request — and replay does not repeat them.

• No recording means no answer. Say that plainly and offer to start one with

orca record claude, rather than falling back to a reconstruction.

Requirements

The orcareplay npm package (Node 20+) with its MCP server registered as orca, and at least one

recorded run in the project's .orca/runs directory. Apache-2.0 —

Continuum-AI-Corp/OrcaReplay.