Open source · Python 3.9–3.13

The undo button for coding agents.

Record every step. Roll back state and files together. Reuse verified runs without another model call.

Install Agent VCR Read the docs

$pip install ai-agent-vcr

task/refactor-auth protected

Recordplanner, model, tool, and state frames

saved

Run failstracked files and .env changed

failed

Roll backstate + workspace restored together

restored

Replay and gateverified identity hit, then Agent CI

passed

Result The fix ships. The failed world does not.

Agents do more than return text.

They edit repositories, call tools, mutate state, and fail halfway through.

A trace can explain the failure. Agent VCR gives you a boundary you can actually restore.

One recovery layer

From “what happened?” to “put it back.”

Use the recorder alone, or combine it with workspace rollback, replay, and CI as your agent becomes more consequential.

Time-travel recording

Capture ordered JSONL frames for nodes, model calls, tools, errors, and checkpoints. Inspect any boundary, compare states, or fork a run.

Recording guide

State + filesystem rollback

Restore Git-tracked work and eligible pre-existing local files to the same savepoint. Modified or deleted ignored files such as .env come back byte-for-byte.

ACID guide

Ghost Replay + Agent CI

Return reviewed outputs on a complete identity match, then compare candidate recordings against versioned expectations before merge.

Replay and CI guide

The hard part is the filesystem

Rollback means the files, too.

Agent VCR creates an isolated Git branch for the transaction and pairs every savepoint with a private local-file snapshot.

Tracked contentRestored from Git savepoint commits.
Ignored and untracked contentEligible pre-existing files are escrowed under .git/vcr-escrow, outside Git objects and VCR recordings.
Safe final commitChanges made after the last savepoint are finalized on the transaction branch before it is merged.
Fail-closed pathsAbsolute paths, .., and resolved-parent symlink escapes are rejected.

Read the transaction contract

workspace.py

from agent_vcr.integrations.openhands import ACIDWorkspace

tx = ACIDWorkspace("/repo")
tx.begin("task-42")

tx.savepoint(
    {"plan": "refactor auth"},
    node_name="planner",
)

# Agent edits code and local files.
tx.rollback(to_frame_index=0)

# Or accept all final work, including
# changes after the last savepoint.
tx.commit()

A tighter debugging loop

Recover the run. Prove the fix.

1
Record
Create a portable execution artifact while the agent runs.
2
Rewind
Return memory and workspace state to the selected boundary.
3
Correct
Patch the prompt, context, tool output, code, or policy.
4
Replay
Reuse verified work only when the full identity still matches.
5
Gate
Compare the candidate recording with reviewed expectations in CI.

Meet agents where they run

Native adapters. A small core API.

Start with your current framework. For custom runtimes, map lifecycle events to the recorder boundary.

LangGraphWrap graph nodes CrewAIAttach callbacks OpenHandsRollback + Sentinel Claude CodeInstall lifecycle hooks n8nRecord workflow events Raw PythonUse four recorder calls

Clear boundary

Local recovery, not magic.

Agent VCR can restore recorded state and repository-local files. It cannot undo email, payments, database writes, or arbitrary external APIs. Put consequential tools behind approvals and explicit compensation.

Start local

Add an undo boundary in minutes.

No hosted account or model key is required for the core recorder, player, workspace rollback, or CI gate.

pip install ai-agent-vcr

python examples/basic_usage.py
vcr tui .vcr/<session-id>.vcr

Open developer docs → View source →