GitHub - ixchio/agent-vcr: Time-travel debugging for AI agents replay, edit, and resume executions without reruns.

Your AI agent corrupted the codebase. Now what?

The only tool that physically deletes hallucinated files — git reset --hard, not just state rollback.

No API keys. No cloud. No vendor lock-in. Works with TERX — memory layer for browser agents.

Your repo after a bad autonomous run:

/src/handlers.py          ← hallucinated, breaks import
/src/auth_v2.py           ← duplicate of auth.py, never needed
/src/models_refactor.py   ← partial rewrite, syntax error
/tests/test_fake.py       ← tests for code that doesn't exist
/config/settings_new.py   ← overwrote working config

from agent_vcr import VCRRecorder
from agent_vcr.integrations.openhands import ACIDWorkspace

recorder = VCRRecorder()
acid = ACIDWorkspace("/my/workspace", recorder=recorder)

acid.begin(session_id="task-001")        # isolated git branch
acid.savepoint(state, node_name="coder") # checkpoint state + filesystem
acid.savepoint(state, node_name="tester")

# Agent writes 47 files. 23 are hallucinated garbage. Step 6 failed.
acid.rollback(to_frame_index=1)
# git reset --hard
# All 23 files: physically deleted from disk. Not hidden. Gone.

acid.commit()                            # merge only the clean branch

Before rollback:          After rollback:
/src/handlers.py    ✗     DELETED
/src/auth_v2.py     ✗     DELETED
/tests/fake_test.py ✗     DELETED
/src/utils.py       ✓     kept
/src/models.py      ✓     kept

from agent_vcr.golden_cache import GoldenRunCache

cache = GoldenRunCache()
cache.save_golden_run("Build a REST API with JWT auth", recorder)

# Every future run of the same task:
outputs, ledger = cache.replay("Build a REST API with JWT auth")
print(ledger)

RUN 1 (original)      RUN 2 (Ghost Replay)
─────────────────     ─────────────────────
Tokens:   4,100       Tokens:      0
Cost:   $0.0123       Cost:    $0.00
Time:  2,350ms        Time:      1ms

💰 100% savings · $0.0123 saved · 4,100 tokens · 2,349ms faster

from agent_vcr import VCRPlayer
from agent_vcr.models import ResumeConfig

player = VCRPlayer.load(".vcr/my_run.vcr")

# See exact state at every step
print(player.goto_frame(6))   # {'files_written': [...], 'plan': '...'}
print(player.get_errors())    # what broke and where

# Fix the prompt. Resume from step 6. Skip steps 0-5.
player.resume(
    agent_callable=coder,
    config=ResumeConfig(
        from_frame=6,
        state_overrides={"plan": "use SQLAlchemy instead of raw SQL"}
    )
)

Without Agent VCR          With Agent VCR
──────────────────         ──────────────────────────
Agent fails step 8         Agent fails step 8
Patch the code             player.goto_frame(7)
Re-run ALL 10 steps        Fix the state
$0.04 + 2 min wasted       Resume from step 7
Repeat for every bug       Done. $0.00 extra.

from agent_vcr import VCRRecorder

recorder = VCRRecorder()
recorder.start_session("my_run")

state = {"query": "build a REST API"}
state = planner(state)
recorder.record_step("planner", input_state, state)

state = coder(state)
recorder.record_step("coder", input_state, state)

recorder.save()  # → .vcr/my_run.vcr

with VCRRecorder() as recorder:
    recorder.start_session("my_run")
    # ... your agent code ...

player = VCRPlayer.load(".vcr/my_run.vcr")

diff = player.compare_frames(5, 6)
# {'added': {'bad_file': '...'}, 'modified': {'plan': '...'}}

player.resume(
    agent_callable=coder,
    config=ResumeConfig(from_frame=5, state_overrides={"plan": "fixed"})
)

from langgraph.graph import StateGraph
from agent_vcr import VCRRecorder
from agent_vcr.integrations.langgraph import VCRLangGraph

recorder = VCRRecorder()
graph = VCRLangGraph(recorder).wrap_graph(graph)  # ← one line, that's it

result = graph.invoke({"query": "Build a todo app"})
recorder.save()

from agent_vcr.integrations.crewai import VCRCrewAI

recorder = VCRRecorder()
recorder.start_session("crew_run")
result = VCRCrewAI(recorder).kickoff(crew)
recorder.save()

pip install "ai-agent-vcr[crewai]"
pip install "ai-agent-vcr[langgraph]"

from agent_vcr.integrations.langgraph import vcr_record

@vcr_record(recorder, node_name="research_step")
def research(state: dict) -> dict:
    return {"findings": search(state["query"])}

from openhands_sentinel import Sentinel

sentinel = Sentinel(recorder=recorder)
sentinel.attach(runtime.event_stream)  # 3 lines. auto-intercepts every write.

STEP 2: Agent writes handlers.py
🛡️ SENTINEL: VIOLATIONS DETECTED
  CRITICAL  hash_password() already exists in auth/utils.py:8 — reuse it
  CRITICAL  handle_auth_request() is 109 lines (limit: 40) — break it up
  CRITICAL  Cyclomatic complexity: 32 (limit: 8)

STEP 3: Agent self-corrects
🛡️ SENTINEL: handlers.py — CLEAN ✓

sentinel scan ./my-ai-project

┌──────────────────────────────────────────────────────────┐
│ 📼 Agent VCR                  Session: my_run · 8 frames │
├──────────────────────────────────────────────────────────┤
│ ▶ Frame 0  │ planner     │ 100ms  │ ●                    │
│   Frame 1  │ researcher  │  250ms │ ●                    │
│   Frame 2  │ coder       │  480ms │ ✗ ERROR              │
│   Frame 3  │ tester      │   80ms │ ●                    │
├──────────────────────────────────────────────────────────┤
│  { "query": "build a todo app", "plan": null }           │
├──────────────────────────────────────────────────────────┤
│ ←/→ navigate  │ e edit  │ d diff  │ r resume  │ q quit   │
└──────────────────────────────────────────────────────────┘

vcr-server .vcr/
# localhost:8000

original_run ──────────────────────────────────────────► [done]
               │ frame 3
               ╰──► fork_v1 ──► [coder] ──► [tester] ──► [done]
               ╰──► fork_v2 ──► [coder] ──► [done]

pip install -e ".[dev]"
pytest tests/benchmarks/ -v --benchmark-only

{"type": "session", "data": {"session_id": "my_run", "created_at": "..."}}
{"type": "frame", "data": {"node_name": "planner", "input_state": {...}, "output_state": {...}}}
{"type": "frame", "data": {"node_name": "coder", ...}}

recorder = VCRRecorder(
    output_dir=".vcr",
    auto_save=True,
    diff_mode=False,
)

recorder.start_session(session_id="my_run", tags=["prod"])
recorder.record_step(node_name, input_state, output_state, metadata)
recorder.record_llm_call(model, messages, response, tokens_input, tokens_output, latency_ms)
recorder.record_tool_call(tool_name, tool_input, tool_output, latency_ms)
recorder.record_error(node_name, input_state, error)
recorder.save() -> Path
recorder.fork(from_frame=3) -> VCRRecorder

player = VCRPlayer.load(".vcr/my_run.vcr")

player.goto_frame(index)           # → output state at frame N
player.get_input_state(index)      # → input state at frame N
player.get_errors()                # → [Frame, ...]
player.compare_frames(a, b)        # → {'added': {}, 'removed': {}, 'modified': {}}
player.get_total_cost()            # → float (USD)

player.resume(
    agent_callable,
    config=ResumeConfig(
        from_frame=7,
        state_overrides={"k": "v"},
        mode=ResumeMode.FORK,      # FORK | REPLAY | MOCK
    )
)

acid = ACIDWorkspace("/workspace", recorder=recorder)
acid.begin(session_id="task-001")
acid.savepoint(state, node_name="coder")
acid.rollback(to_frame_index=2)    # git reset --hard
acid.commit()

cache = GoldenRunCache(cache_dir=".vcr/golden")
cache.save_golden_run(task_description, recorder)
outputs, ledger = cache.replay(task_description)
cache.invalidate(task_description)
cache.list_golden_runs()

# ACID rollback + Ghost Replay — start here
python examples/acid_golden_run.py

# Time-travel: rewind, edit state, resume
python examples/time_travel_demo.py

# Sentinel: watch agent self-correct in real time
python examples/sentinel_demo.py

# LangGraph auto-instrumentation
python examples/langgraph_integration.py

# Basic recording and playback
python examples/basic_usage.py

git clone https://github.com/ixchio/agent-vcr.git
cd agent-vcr
pip install -e ".[dev,tui]"
pytest tests/unit/ -v