rewind-llm 0.2.0

Record-replay debugger for AI agent runs

rewind

Record-replay debugger for AI agent runs. Time-travel debugging for agent harnesses.

An agent only touches the outside world through a narrow boundary: model calls in, tool calls out. rewind captures everything crossing that boundary, then replays it exactly — or branches from any step to explore alternate trajectories.

Installation

pip install rewind-llm

With optional SDK extras:

pip install rewind-llm[anthropic]   # Anthropic SDK support
pip install rewind-llm[openai]      # OpenAI SDK support

Quickstart — SDK instrumentation

from rewind import Session, Mode, instrument

session = Session(mode=Mode.RECORD, trace_path="run.jsonl")

# One line — captures all HTTP traffic through the SDK client.
instrument(client, session)

# Your agent code stays exactly the same:
response = client.messages.create(model="claude-sonnet-4-20250514", messages=[...])

Tools still use the decorator:

@session.tool
def search(query: str) -> str:
    return my_search_api(query)

Record → Replay → Branch

# RECORD a run
session = Session(mode=Mode.RECORD, trace_path="run.jsonl")
instrument(client, session)
run_my_agent(client)

# REPLAY it — exact same trajectory, no API calls
session = Session(mode=Mode.REPLAY, trace_path="run.jsonl")
instrument(client, session)
run_my_agent(client)  # returns recorded results

# BRANCH at step 2 — inject a different model response, go live after
session = Session.branch("run.jsonl", "branch.jsonl", at_step=2,
                         override=my_edited_response)
instrument(client, session)
run_my_agent(client)  # replays steps 0-1, injects override at 2, live from 3+

CLI proxy recording

Record and replay CLI tool sessions through a transparent HTTP proxy — no code changes required.

# Record a Claude Code session
rewind record -- claude "fix the bug"

# Replay it (no API calls, instant)
rewind replay traces/anthropic_20260101_120000.jsonl -- claude "fix the bug"

# Standalone proxy (connect your tool manually)
rewind proxy --mode record --trace session.jsonl

The proxy intercepts HTTP traffic between your CLI tool and the AI provider, capturing every request/response pair.

Provider auto-detection

The proxy auto-detects the AI provider from the command name and sets the appropriate environment variable:

Command	Provider	Env var
claude, claude-code	Anthropic	ANTHROPIC_BASE_URL
opencode, aider	OpenAI	OPENAI_BASE_URL
gemini	Gemini	GOOGLE_GEMINI_BASE_URL
agy	Antigravity	ANTIGRAVITY_BASE_URL

CLI commands

rewind ls                                           # List traces
rewind show <trace.jsonl>                           # Pretty-print
rewind diff <a.jsonl> <b.jsonl> [--html out.html]   # Diff traces
rewind branch <trace> --at N --edit|--inject|--live  # Branch
rewind migrate <traces>...                          # v0 → v1
rewind record -- <cmd>                              # Record via proxy
rewind replay <trace> -- <cmd>                      # Replay via proxy
rewind proxy --mode record|replay --trace <file>    # Standalone proxy

Configuration

Variable	Default	Description
REWIND_TRACE_DIR	traces	Directory for storing trace files

# Store traces in a custom directory
export REWIND_TRACE_DIR=~/.rewind/traces
rewind record -- claude "fix the bug"

# List traces from a custom directory
REWIND_TRACE_DIR=/tmp/test rewind ls

How it works

Transport capture

instrument(client, session) swaps the httpx transport inside your SDK client (Anthropic or OpenAI). Every HTTP request/response is captured transparently — no changes to your agent code.

Normalization

Real requests contain volatile fields (timestamps, request IDs, SDK versions) that change on every run. rewind strips these before hashing so irrelevant changes don't cause false divergences. Configure with MatchConfig:

from rewind import MatchConfig, Session, Mode

config = MatchConfig(
    ignore_headers=["x-request-id", "date"],
    ignore_body_paths=["metadata.session_id"],
    ignore_body_patterns=[r"[0-9a-f-]{36}"],  # UUIDs
)
session = Session(mode=Mode.REPLAY, trace_path="run.jsonl", match_config=config)

Structured divergence reports

When inputs don't match, DivergenceError carries a DivergenceReport showing which fields differ and whether each was marked as ignorable — so you can tighten config in one pass.

Modes

• RECORD: executes for real, appends each request/response to a JSONL trace
• REPLAY: returns recorded results by step order, verifies inputs via normalized SHA-256 hash
• BRANCH: replays up to step N, injects an override or goes live, writes a child trace

Development

pip install -e ".[dev]"
python -m pytest tests/ -v

No API key required — tests use MockTransport and MockModel.

License

MIT