Documentation · v1.5.4 · Python 3.9–3.13

Build agents with an undo boundary.

Start with recording, add workspace rollback where files matter, promote reviewed runs to identity-aware replay, and gate the next change in CI.

Start building View on PyPI ↗

Core

Record and time-travel

Capture typed execution frames, inspect state, compare boundaries, resume, and export portable bundles.

Filesystem

ACID workspace rollback

Restore tracked Git content and eligible pre-existing local files such as ignored .env files.

Reuse

Identity-aware Ghost Replay

Reuse reviewed outputs on a full identity match and rerun changed work through explicit partial modes.

Reliability

Agent CI

Compare real candidate recordings with reviewed baselines and enforce state, tool, cost, token, and latency expectations.

Connect

Framework integrations

Use raw Python, LangGraph, CrewAI, OpenHands, Claude Code hooks, n8n, or your own lifecycle adapter.

Operate

Workflows and self-hosting

Add durable workflow state, approvals, compensation, reliability intelligence, and a local dashboard/server.

Quick start

The base install is local-first and needs no model key, hosted account, or framework.

terminal

pip install ai-agent-vcr

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

Package name: install ai-agent-vcr. The similarly named agent-vcr package on PyPI is a different project.

Record a state transition

The recorder is the framework-neutral boundary. A session contains ordered JSONL frames for nodes, model calls, tools, errors, and checkpoints.

agent.py

from agent_vcr import VCRPlayer, VCRRecorder

recorder = VCRRecorder(output_dir=".vcr")
recorder.start_session("support-triage")
recorder.record_step(
    "classify",
    {"status": "new"},
    {"status": "classified", "priority": "high"},
)
recording = recorder.save()

player = VCRPlayer.load(recording, strict=True)
print(player.goto_frame(0))
print(player.verify_integrity())

Full recording, resume, bundle, and privacy guide →

Rollback state and files together

ACIDWorkspace combines isolated Git savepoints with private, per-savepoint local-file escrow.

Tracked contentRestored from the selected Git savepoint commit.

Local contentEligible untracked/ignored files restored byte-for-byte with modes and symlink targets.

Secret boundaryEscrow bytes stay under .git/vcr-escrow, outside Git objects and VCR recordings.

Issue #2 guarantee: a modified or deleted pre-existing .env is restored at rollback, while later hallucinated local files are removed. Oversized, excluded, and special files are preserved but cannot be reconstructed.

Blobs are immutable and content-addressed as blobs/<sha256>.
Escrow directories use 0700; regular blobs use 0600.
Paths containing .., absolute paths, and resolved-parent symlink escapes are rejected.
Rollback can run repeatedly before commit; shared blob references stay valid.

Full transaction lifecycle, limits, and threat boundary →

Ghost Replay without silent drift

A golden run is selected by the normalized task plus an optional identity covering model, prompt, code, tools, dependencies, environment, and caller-defined fields.

replay.py

from agent_vcr.golden_cache import GoldenRunCache

cache = GoldenRunCache()
identity = cache.build_identity(
    model="provider/model@revision",
    prompt_hash="sha256:prompt",
    code_commit="0123456789abcdef",
    tool_schema_hash="sha256:tools",
)
cache.save_golden_run("triage ticket", recorder, identity=identity)
outputs, ledger = cache.replay("triage ticket", identity=identity)

Nested identity JSON uses canonical sorted-key serialization. Key-order changes do not cause false misses; actual identity changes do.

Gate changes with recorded evidence

Generate candidates with the code under review, then compare them with versioned baseline cases. The gate itself makes no model calls.

terminal

vcr dataset create refunds
vcr dataset add refunds \
  --task "refund a duplicate payment" \
  --case-name duplicate-payment \
  --vcr .vcr/reviewed/refund.vcr

vcr ci run \
  --dataset refunds \
  --candidates .vcr/candidates \
  --fail-on degraded \
  --report agent-ci-report.json \
  --markdown agent-ci-report.md

Full dataset, candidate, and GitHub Action guide →

Connect your agent runtime

Native adaptersLangGraph nodes, CrewAI callbacks, OpenHands Sentinel, and ACIDWorkspace.

Claude CodeInstall lifecycle hooks with vcr init --claude-code.

Custom runtimesMap lifecycle events to record_step, record_llm_call, record_tool_call, and record_error.

Full framework integration guide →

Production building blocks

Workflow engine — durable runs, resume, schedules, approvals, retries, and saga compensation.
SuperAgent — validated plans, policy, budgets, tool schemas, and output verification.
Sentinel — local AST quality analysis and optional OpenHands feedback.
Railway foundation — optional auth/billing control plane with an explicit multitenancy boundary.
Benchmark dashboard — measured history and local regression ceilings.

External effects are outside Git. Agent VCR cannot undo email, payments, database writes, or arbitrary APIs. Use approvals before consequential tools and explicit compensation where reversal is possible.