# orca-replay

Adopt this skill: https://proskills.md/skills/other/continuum-ai-corp-orcareplay-skills-orca-replay

Page: https://proskills.md/skills/other/continuum-ai-corp-orcareplay-skills-orca-replay
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/orca-replay/SKILL.md
size: 8042
upstream: https://github.com/continuum-ai-corp/orcareplay/blob/main/skills/orca-replay/SKILL.md

```text
---
name: orca-replay
description: Answers questions about a past agent run from its recording rather than from memory, and replays or forks that run. Use when asked why an earlier run did something, or to reproduce a failure.
license: Apache-2.0
compatibility: Requires 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.
metadata:
  author: Continuum-AI-Corp
  version: "0.1"
  homepage: https://github.com/Continuum-AI-Corp/OrcaReplay
---

# Reading a recorded agent run

A recording is evidence. Your memory of a session is not, and neither is a transcript you were
handed — both are missing the tool results, the exit codes, and the files that changed without
anyone mentioning it.

**The rule: when a question is about something that already happened, read the trace before you
answer.** 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?" / "Which step broke the build?"
- "Can you reproduce yesterday's failure?"
- "Does this still reproduce?" (see the limit on that in step 4 — replay cannot tell you
  whether a *fresh* run would fail again)
- "Would a different model have got this right?"

## Workflow

### 1. Find the run

`orca_list_runs` — newest first, and it names the run each fork came from. Skip this only when the
user clearly means the most recent one; every other tool defaults to `run: "last"`.

### 2. Narrow to the chain that produced the thing being asked about

`orca_show_run` gives the whole timeline: model turns with token counts and stop reasons, tool
calls with arguments and results, shell commands with exit codes, and every file the run changed.
Good for orientation, long for a specific question.

`orca_graph` is usually the better tool. It returns causal edges — which event produced which. Pass
`to: <event seq>` to get **only** the chain that produced one event. That is the shape of an answer
to "why did this happen", where the full timeline is the shape of an answer to "what happened".

### 3. Report `recorded` and `inferred` differently

Every edge from `orca_graph` is labelled:

- **`recorded`** — the recorder watched it happen and wrote it into the trace.
- **`inferred`** — derived just now from a rule the edge names. The trace does not vouch for it.

Carry that distinction into your answer. "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 flattening them into one
confident sentence is the specific failure this tool exists to prevent. Name the rule when you lean
on an inferred edge.

### 4. Reproduce it before explaining it

`orca_replay` re-runs the recording and reports what could not be reproduced — divergences, and
requests the recording could not serve.

**What "offline" covers, and what it does not.** Every model response comes from the trace and the
proxy forwards nothing upstream, so no provider is contacted and no tokens are spent. An unmatched
request halts the replay rather than falling through to the network, unless `--loose` was asked for.

That covers the model traffic. It does not cover the agent's own subprocesses: unless the recording
used `--tls-intercept` — in which case replay re-establishes interception for the hosts it recorded
— a `curl`, `npm install`, `git push` or database call inside a recorded shell command goes
straight out. Replay is not a sandbox; only a network-isolated container makes it one.

**What a matching replay proves, and what it does not.** It shows the recorded decisions reproduce
against today's environment. It cannot show the failure is deterministic, because the model is not
being asked again — the same recorded responses are served back. If the user wants to know whether a
fresh run would fail the same way, say that replay cannot answer it; that needs real runs.

**Replay re-executes the agent, not just its model traffic.** The recorded model responses are
served from the trace, but the agent process runs again for real — so every shell command it issued
runs again too. `worktree: true` isolates repository files and nothing else. Anything the run
touched outside the tree — `/tmp`, Docker, a local database, a package manager, another host — is
mutated a second time.

**So check before the first replay of a run, not after.** Read its shell commands with
`orca_show_run` and tell the user what will re-execute. If any of it reached outside the working
tree, get approval for that specifically or replay inside a container; do not treat the earlier
`worktree` answer as covering it. A run that only read files and edited the repository is free and
repeatable, and worth replaying before committing to any explanation.

**Pass `worktree: true`.** It replays into a scratch copy and leaves the working tree alone.

Without it, replay is destructive for as long as it runs: it restores the recorded filesystem over
the working tree and puts the tree back when the replay ends. Uncommitted work is absent in the
meantime, and stays absent if the replay is interrupted before it can restore. Run an in-place
replay only when the user has been told that and has agreed to it. "They do not appear to be
typing" is not consent.

A replay reporting `reused=3/5` on an interactive recording is not a partial failure. Harnesses make
calls for themselves — a quota probe, a session-naming request — and a replay does not repeat them.

### 5. Only then consider comparing models

`orca_compare` forks one run onto several models from the same checkpoint: same files, same
conversation prefix, so the model is the only variable. Pick the fork point with `orca_checkpoints`
and pass it as `from`.

Grade with `verify` — a shell command whose exit code is the verdict. Use something the repository
already declares (`"npm test"`, `"npm run typecheck"`) or an explicitly local binary
(`"./node_modules/.bin/tsc --noEmit"`), not `npx <tool>`: with no local install, npx runs whatever
the registry has under that name, and `npx tsc` resolves a package deprecated in 2016 that is not
TypeScript.

**`orca_compare` uploads the recording to other people's models, and spends real money doing it.**
Each model named receives the same files and conversation prefix the original run had — so whatever
that run touched (source, prompts, configuration, anything a credential was pasted into) is sent to
every provider behind those model ids.

**And each fork is a live agent, not a replay.** From the fork point onward the model is really
being asked, and whatever it decides to do, it does — its shell commands execute for real, and so
does the `verify` command you pass. Each fork gets its own worktree, so repository files are
isolated per model; nothing outside the tree is. A fork can also take actions the original run never
took, because it is a different model making fresh decisions.

So the approval has three parts, and they are not the same question:

1. **Disclosure** — what context is uploaded, and to which providers. Approving a bill is not
   approving a disclosure, and the two need separate answers when the recording is from a private
   codebase. `orca scrub` is for when the comparison is worth running but the trace is not safe to
   send as-is.
2. **Side effects** — what the recorded run did outside its worktree, since each fork may repeat it
   and may go further. Same check as step 4, `orca_show_run`, and the same answer if it reached
   Docker, a database, a deployment or another host: get approval for that specifically, or run the
   comparison in an isolated environment.
3. **Cost** — how many models times how many forks.

Never run it to satisfy curiosity the user did not express.

## If there is no recording yet

Say so plainly rather than falling back to guessing, and offer to start one.

If `orca` is a
```

## File: README.md
upstream: https://github.com/continuum-ai-corp/orcareplay/blob/main/README.md

````text
# OrcaReplay
<sub>**English** · [简体中文](docs/i18n/README.zh-CN.md) · [日本語](docs/i18n/README.ja.md) · [한국어](docs/i18n/README.ko.md) · [Deutsch](docs/i18n/README.de.md) · [Français](docs/i18n/README.fr.md) · [Español](docs/i18n/README.es.md) · [العربية](docs/i18n/README.ar.md)</sub>

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

<a href="https://www.orcarouter.ai">
  <img src="docs/orcarouter.svg" alt="OrcaRouter" height="28" align="left" hspace="10">
</a>

**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](https://www.orcarouter.ai/models) 

Github Repos: [OrcaCode Review](https://www.orcarouter.ai/code-review) · [OrcaRouter Lite](https://github.com/Continuum-AI-Corp/OrcaRouter-Lite) 

Connect: [X](https://x.com/OrcaRouter) · [Discord](https://discord.com/invite/YEubt8enRA) · [Hugging Face](https://huggingface.co/orcarouter) · [Ollama](https://ollama.com/orcarouter)

<br clear="left">

[![License](https://img.shields.io/badge/code-Apache--2.0-blue)](LICENSE)
[![Spec](https://img.shields.io/badge/trace%20spec-CC%20BY%204.0-blue)](spec/orca-trace-v0.md)
[![Node](https://img.shields.io/badge/node-20%2B-brightgreen)](#install)
[![Agents](https://img.shields.io/badge/agents-Claude%20Code%20%C2%B7%20Codex%20%C2%B7%20Agents%20SDK%20%C2%B7%20AI%20SDK%20%C2%B7%20any-black)](#which-agents)
[![Good first issues](https://img.shields.io/badge/good%20first%20issues-12-orange)](docs/good-first-issues.md)
[![Mentioned in Awesome Claude Code](https://awesome.re/mentioned-badge.svg)](https://github.com/hesreallyhim/awesome-claude-code)

![Recording a Claude Code run, replaying it offline, then forking it onto two models](docs/demo-cli.gif)

<sup>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.</sup>

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

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

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

```console
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`](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.

|  | Observability tools | OrcaReplay |
|---|---|---|
| Tells you what a run cost | ✅ | ✅ |
| Tells you which tool call deleted the file | sometimes | ✅ |
| Runs the agent again and gets the same answer | ❌ | ✅ from the recording, byte-for-byte |
| Lets you change the model and re-run from step 4 | ❌ | ✅ |
| Needs you to modify your agent | usually an SDK wrapper | ❌ two env vars |
| Works after you close the terminal | ❌ | ✅ it is a file |
| Sees past the model API — shell exit codes, file writes | ❌ | ✅ every turn |
| Records an agent with no API endpoint to redirect | ❌ | ✅ opt-in `--tls-intercept` |

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](#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](#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.

```mermaid
%%{init: {'theme':'neutral'}}%%
flowchart LR
    A["<b>your agent</b><br/><i>unmodified</i>"]

    subgraph orca["orca · six capture layers"]
        direction TB
        P["<b>proxy</b><br/>base-URL env var"]
        
````
