Contents
docs

Replay your agent, not a trace of it.

shadowlap is change safety for agents: every change to an agent (its code, its prompt, its model, a tool, the route to its provider) is checked against what the agent actually did.

Where to start

  • shadowlap run

    Quickstart

    Record and replay the bundled reference agent in two minutes, then your own.

  • shadowlap replay

    How it works

    Calls that haven't changed come from the recording; the first one that differs gets a diff, and the run forks there.

  • blame · repair · verify

    Fixes

    Blame finds the model call that lost a run, repair rewrites the prompt, and verify proves the fix on failing, held-out and good runs.

  • shadowlap test

    CI mode

    A run kept as a golden, replayed offline on every pull request.

  • shadowlap dashboard

    Dashboard

    Your recordings in a browser: each call as the model saw it, where a replay forked, and what it cost.

  • --json

    Coding agents

    Claude Code, Cursor and Codex drive shadowlap through the CLI, and every command they need reads and writes JSON.

Go further

  • request_changed

    Why did my replay diverge?

    Start from the report: it names the call, the type of divergence and the exact paths that differ.

  • --override · --fail-at

    Interventions

    Change one thing at one point, so everything before it still replays for free.

  • cassettes · tracing · evals

    Compared with other tools

    Cassettes, tracing and eval platforms, replay evals, agent debuggers, framework time travel and durable execution, and where each is the better choice.

  • shadowlap import litellm

    Capturing production traffic

    Turn a run that went wrong in production into a recording, through a gateway already in the request path.

  • shadowlap push

    Team store

    Your team's runs in a bucket you own, pushed and pulled with your own credentials, with pull requests kept to their own folders, and share links.

  • shadowlap export pairs

    Training

    The preference pairs your blames and verifies already left in the store, exported for fine-tuning, and goldens as tasks a model is scored on.

Build on shadowlap

  • POST /v1/calls/resolve

    Wire protocol

    The HTTP API the SDKs speak to the sidecar, for an SDK in a language shadowlap doesn't ship.

  • packs · serve --recordings

    Recording format

    Recordings as shadowlap writes and reads them: on disk as a pack, and over HTTP as the protocol a test runner records and replays through.

  • @shadowlap/engine

    Engine as a library

    The package the CLI, the sidecar and the dashboard are built on, for an importer, a viewer or your own CI integration.

What it is for

#

Each job below, done without shadowlap and with it:

JobWithout shadowlapWith shadowlap
Reproduce a failing runRe-run and hope; pay for the whole run againshadowlap replay <run>: same run, zero upstream requests
Find where a failed run went wrongRead the trace and guessshadowlap blame <run>: the model call that lost the run, found with forks that replay everything before it for free
Fix a prompt the agent keeps misreadingEdit it by hand, rerun, repeatshadowlap repair: a model you choose proposes rewrites, and the smallest one verify accepts comes back as a patch with its evidence
Know a fix works before it shipsRerun the failing case once and hopeshadowlap verify: the failing runs fixed, runs it was not written against too, and the good runs kept, several attempts each
Fix a harness bug (parsing, dispatch, state, stop condition)Re-run live; the model may behave differently this timeFull replay against the recorded model behavior; the bug reproduces every time
Verify a fix that changes later requestsRe-run everything live, side effects includedUnchanged prefix replays; only the changed suffix runs live; writes are blocked or stubbed
Ask "what if call 9 had returned X?"Hand-edit code and re-run--override 9=@x.json, and only the calls after it run live
Catch unintended prompt changes in CIString snapshot testsshadowlap test fails the build on the first changed request
Know what a prompt edit or a model switch decides differentlyRun every golden live and read the transcriptsshadowlap decisions: each recorded model call asked again with only the change, ranked by consequence, writes first; shadowlap migrate for a model switch, verified and priced

Three sentences to keep in mind

#
  1. A replay forks at the first request that changes, not where the bug is.

    Fixes to the code around the model change no request and replay in full. Editing the system prompt changes every request and forks at call 1: you get the diff and a fenced fork, but no savings. See How it works.

  2. Nothing is matched fuzzily.

    Two requests match only if they are identical after the normalizers you wrote. A false replay hit would be the worst bug this tool could have, so it reports a false divergence instead and shows you how to fix it.

  3. Side effects that don't go through shadowlap will run again.

    Wrap tools with the SDK or a framework adapter. A tool the model called that the run never recorded is named, and a replay won't run one that writes until you wrap it, declare it a read or allow it. Anything else, such as a direct database client or an unwrapped HTTP call, is invisible to replay.

This page on GitHub →