pmlucero/retrace

Record, replay and diff AI agent sessions. Swap the model, freeze the tools, see exactly where behavior diverges.
> Status: MVP in progress. The design (phase 0) is approved, and implementation has started. There is no usable release yet. See Project status.
## What is retrace
retrace is a VCR for AI agents. It is a transparent proxy, shipped as a single Go binary, that sits between your agent and:
the LLM API (Anthropic Messages API, including streaming), and
your MCP servers (Streamable HTTP).
It records every session into a cassette. You can then replay that session deterministically while changing exactly one variable:
Keep the tools frozen and swap the model to see what a different model would have done with the exact same tool results.
Keep the model's decisions and run the live tools to detect when a tool's behavior has drifted.
Diff two sessions to find the first step where they diverge: the step, the tool and the arguments.
Enabling it requires no SDK and no code changes. You point the agent's base URLs at retrace.
## How it works
Record: the proxy forwards each request upstream, streams the response back unbuffered, and enqueues it for the cassette without ever blocking the agent.
Replay: the router answers a channel from the source cassette by request fingerprint, or forwards it live, depending on the mode. Every replay writes a new cassette.
Diff: compares the trajectories of two cassettes and reports the first divergence.
The diagram source and how to regenerate it are in docs/architecture.
## What retrace is not
retrace is not an observability or tracing tool. Langfuse, LangSmith, Phoenix and OpenTelemetry already do that well. retrace is about replay and experimentation, and it is designed to be used alongside your tracing stack, not instead of it. See docs/vision.md.
## Replay modes
| Mode | Model | Tools | Use it to… |
| exact | recorded | recorded | Debug a session offline, for free, with no network. |
| swap-model | real, different model | recorded | Compare models under identical tool results. |
| live-tools | recorded | real | Detect tool drift against recorded model decisions. |
| diff | — | — | Find the first divergence between two trajectories. |
When a replay hits something that was never recorded, retrace stops by default (strict) and reports the exact divergence point. It never invents a response silently.
## CLI at a glance
> Tentative. The authoritative definition is in the spec.
sh
# Record a session (the agent reads ANTHROPICBASEURL and RETRACEMCPURL)
retrace record --session checkout --mcp orders=http://localhost:9001/mcp \
--mcp email=http://localhost:9002/mcp -- python agent.py
# Replay it offline, exactly
retrace run checkout
# Same tool results, different model
retrace run checkout --model --tools frozen