⏪ rewind

A time-travel debugger for LLM agents.

Agents are black boxes. Something goes wrong on step 7 and you can't see why, can't reproduce it, and can't test a fix without running the whole thing again.

rewind records every model call your agent makes, then lets you replay reality from any point — inspect the exact context, edit a past step, and re-run to see what would have happened.

$ rewind ls run.jsonl
  #  model              msgs   in→out tok     lat  stop       preview
  0  claude-opus-4-8       1      412→38     1.8s  tool_use   🛠  get_weather
  1  claude-opus-4-8       3      498→41     1.3s  end_turn   Bring a warm waterproof jacket…
  2  claude-opus-4-8       5      561→36     1.7s  tool_use   🛠  get_weather   ← wrong city!

$ rewind fork run.jsonl 2 --append-user "Use the city I just asked about, not Paris."
replaying step 2…

══════════════════════════════════════════════════════════
  original (step 2)
  🛠  get_weather({'city': 'Paris'})
  stop=tool_use out_tok=36 lat=1.7s
══════════════════════════════════════════════════════════
  forked outcome
  🛠  get_weather({'city': 'Rome'})        ← fixed
  stop=tool_use out_tok=34 lat=1.6s

---

Why

LLM observability tools (LangSmith, Langfuse) show you what happened. rewind lets you ask "what if?" — the thing you actually need when debugging a non-deterministic agent:

• Record with one line. RewindClient is a drop-in for anthropic.Anthropic(). No callbacks, no decorators, no SaaS account.
• See the real context. rewind show prints the exact messages, system prompt, and tools that went into any call — not a reconstruction.
• Fork the timeline. Pick any step, edit the prompt / system / model, and re-run from there. Compare outcomes side by side.
• Local-first. Traces are plain JSONL on your disk. Grep them, diff them, commit them as regression fixtures.

Install

pip install llm-rewind

Record a run

Wrap your client. That's the whole integration:

from rewind import RewindClient

client = RewindClient(trace_path="run.jsonl")   # instead of anthropic.Anthropic()

# ...use it exactly like the normal SDK; every messages.create() is recorded
client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "..."}],
)

Everything else on the client (beta, models, stream, …) passes straight through to the real SDK.

Debug it

rewind ls run.jsonl            # timeline of every model call
rewind show run.jsonl 2        # the full context + response of call #2
rewind fork run.jsonl 2 \      # re-run call #2 with an edit and diff the result
    --system "You are concise." \
    --model claude-sonnet-4-6

fork flags:

flag	what it does
--system TEXT	replace the system prompt
--model NAME	replay on a different model
--append-user TEXT	add a user message before replaying
--set-message IDX TEXT	overwrite message at IDX (negative indexes ok)
--max-tokens N	override max_tokens
--out FILE	write the fork to a separate trace

Forks are appended to the trace (with a parent link) so they show up in ls and you can show them like any other step.

Try it now (no key needed)

git clone https://github.com/oavlloh-wq/rewind && cd rewind
pip install -e .
python examples/make_demo.py
rewind ls examples/demo.jsonl
rewind show examples/demo.jsonl 1

ls and show work fully offline. fork needs ANTHROPIC_API_KEY since it calls the live model.

How it works

A trace is a JSONL file — one line per messages.create call, capturing the exact request and response (model, system, messages, tools, content, stop reason, token usage, latency). fork loads a step, applies your edits to its request, and replays it against the API; the result is written back as a new step whose parent points at the original, so the branch is part of the same trace. No magic, no lock-in — you can read the format with cat.

Roadmap

• Replay a whole loop from a step (re-execute tool calls), not just one turn
• Web timeline UI with branch visualization
• rewind diff A B for arbitrary step comparison
• Streaming + messages.stream() recording
• Cost rollups per run and per branch
• Adapters beyond Anthropic

PRs welcome.

License

MIT

---

_{If rewind saved you a debugging session, drop it a ⭐.}