OrcaReplay MCP
OrcaReplay records a coding agent run, replays it with no model call and in MCP mode answers an agent from the recordings.
- 591 ★ on the repository
- Last commit
- Apache-2.0
Extended access
Why this level
- Model comparison reaches the network and is paid for in tokens.
- Run recordings can hold secrets and personal data from the shell and files.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add mcp/orcareplayDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Model comparison reaches the network and is paid for in tokens.
- Run recordings can hold secrets and personal data from the shell and files.
This is third-party code. Review the repository files before installing.
What it does
OrcaReplay records the work of any coding agent, replays a run byte for byte offline with no model call and forks a run from any step onto another model. The npm package is `orcareplay` and the `orca` command lands on PATH. Recording is done by a proxy below the agent level that sees model calls, shell exit codes and file writes. The package has an MCP server started with `npx -y orcareplay mcp`. Six tools answer an agent from recordings: `orca_list_runs` lists runs, `orca_show_run` gives the full timeline, `orca_checkpoints` lists checkpoints, `orca_graph` shows the event chain, `orca_replay` replays with no network or spend and `orca_compare` reruns on several models graded by a command. The last one spends real tokens and reaches the network.
Who it is for. People who investigate coding agent failures and compare models and want to ask questions about recorded runs right from Claude Code or Codex.
Good fit when
- An agent deleted a migration file overnight and in the morning the run is replayed with no model to find the call.
- For a recorded run the divergence on replay and the call timeline are requested.
- A run is forked at step four onto two models and graded with `npm test`.
- Run checkpoints are read by an agent to choose a step to fork at.
Not a fit when
- The agent was not run through `orca record`: there are no recordings to ask about.
- The token budget is closed: model comparison calls each of them.
- An ordinary observability dashboard with cost and tokens is wanted: OrcaReplay solves replay.
Example request
List the recorded runs, replay the last one with no model and tell me where it diverged from the recording.MCP
- Transport
- stdio
- Authentication
- not required
Limitations
The server answers only from recordings made in this project with `orca record`, and recording needs an installed agent, a key, a network and tokens. The `orca_compare` tool really calls the named models and spends tokens, and its description asks to confirm with the user first. Replay without a network works from recorded answers, so it checks the run itself rather than a new model answer. The package needs Node.js 20 or newer. A recording sees the shell, the filesystem and MCP, so secrets and personal data can end up in it.
How to disable. Remove the `orcareplay` entry from `.mcp.json` or the client settings. Run recordings live in the project as files and stay.
FAQ
How do I connect MCP?
Add an `orcareplay` server to `.mcp.json` with the command `npx` and arguments `-y`, `orcareplay`, `mcp`. Install the package with `npm i -g orcareplay`.
How do I record a run?
Run `orca record claude` instead of launching the agent directly, then `orca replay last` repeats it with no network or tokens.
What spends tokens?
Only `orca_compare`: it really calls the named models. `orca_replay` works without a network.
How do I try it without my own agent?
Run `orca quickstart`: it creates a small project with a bug and a recording of the fix and replays it with no model.
Which agents can be recorded?
Claude Code, Codex, Agents SDK, AI SDK and any agent whose API address can be overridden with two environment variables.
Discussion
No questions or reviews yet.
Related
MCP serversA skill breaks a requirement into an Orca task graph, and a browser viewer shows it and runs workers along the dependencies.
Official OrcaRouter MCP server: a model catalog with pricing and chat with auto-routing and a fallback chain.
One runtime for Claude Code, Codex, OpenCode and more: a run counts as done only when checks the agent did not write pass
A terminal coding agent in one Rust binary that reads code, edits files and runs tests with any model of your choice.
AgentOps MCP server: the agent reads traces and spans of agent runs to find where they failed
A local whiteboard and MCP server for research agents: every claim is tied to the run and the code that produced it
README in short
The README explains the goal, three launch commands, how recording differs from ordinary observability and lists supported agents. MCP tools are described in the server code.