OrcaReplay: Record and Replay AI Agent Runs

Overview

OrcaReplay is a command-line tool for recording AI agent runs and examining their model requests, tool calls, shell activity, and filesystem changes together. It addresses a common debugging problem: rerunning an agent may produce a different result, making it difficult to identify what caused a failure.

Recorded interactions can be replayed offline, or continued from a checkpoint with another model. This makes OrcaReplay useful when you need to reproduce a bug, inspect a run after it ends, or compare models on the same task. It captures agents through proxy and process-level integrations rather than requiring changes to the agent's code.

Key Features

• Records model traffic and agent activity in a local trace.
• Replays recorded model interactions offline, with unmatched model requests blocked by default.
• Forks runs from checkpoints and compares models on the same recorded prefix.
• Shows a timeline of model calls, tool results, shell activity, and filesystem changes.
• Exports runs as standalone HTML and provides commands for machine-readable JSON output.
• Offers an MCP server and a TypeScript API for accessing and replaying traces.
• Supports multiple agent frameworks and command-line agents, with TLS interception available for selected cases where endpoint redirection is not possible.

Use Cases

• An agent developer can inspect a failed run to find the tool call, command, or file change associated with a bug.
• A team debugging intermittent behavior can replay a saved run offline instead of relying on a new run to reproduce it.
• An evaluator can fork one task from a checkpoint across models and compare outcomes under a shared prefix.
• A maintainer can share a self-contained trace export when asking others to investigate an agent failure.

Getting Started

Install the CLI with Node.js 20 or newer:

npm i -g orcareplay
orca doctor

For example, record and replay a Claude Code run with orca record claude and orca replay last. See the README for agent setup, configuration, and command details.

Alternatives

• langwatch: LangWatch provides broader LLM and agent observability, evaluation, and production monitoring, rather than focusing on offline run replay and checkpoint forking.

Considerations

OrcaReplay requires Node.js 20 or newer. The README describes the project as early and its trace format as version 0. Although offline replay blocks unmatched model requests by default, replayed tools can still have real side effects, and tools that open their own network connections are not automatically sandboxed. Traces may contain sensitive information, so treat them as sensitive data and review or scrub them before sharing. TLS interception is opt-in and requires trusting a run-specific certificate within the launched agent.