Time-Travel Debugger & In-Memory Hot-Code Patcher for Python
Record execution state history, scrub backward through function milestones, inspect variable mutations, and test fixes in memory before saving to disk.
When a script or pipeline crashes, Python produces a traceback:
TypeError: unsupported operand type(s) for +: 'float' and 'NoneType'
File "pipeline.py", line 38, in finalize_invoice
final_total = order["subtotal"] + order["tax"]
The traceback shows where the code failed (the symptom), but not why order["tax"] was None (the root cause). The actual bug often happened several functions earlier (e.g., an unhandled condition in an upstream session initializer).
Traditional debuggers (pdb, IDE breakpoints) are forward-only and post-mortem:
- Once the process crashes, execution terminates and in-memory state is lost.
- Stepping too far means restarting the entire process from the beginning.
- Finding where a variable was corrupted usually requires adding temporary
print()calls and restarting repeatedly.
Rewind solves this by recording an execution timeline:
- Scrub Backward: Step backward through function frames (
J/K) to see earlier states without restarting. - Inspect Diffs: View exact variable additions, mutations, and deletions between function boundaries.
- Hot-Replay in RAM: Edit broken lines directly in the browser and re-execute in ~0.14 ms to verify fixes.
- Patch to Disk: Atomically write verified fixes to disk with automatic
.bakbackups.
REWIND ARCHITECTURE
┌────────────────────────────────────────────────────────┐
│ 1. Instrumentation (rewind/cli.py) │
│ • Hooks Python execution via sys.settrace() │
│ • Captures inputs, outputs, and uncaught exceptions │
└──────────────────────────┬─────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────┐
│ 2. State & Diff Engine (rewind/diff.py, tracer.py) │
│ • Circular-safe object serialization │
│ • Structural state diffing (+ Added, ~ Mutated) │
│ • Exports portable rewind_trace.json │
└──────────────────────────┬─────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────┐
│ 3. Web Scrubber & Hot Sandbox (localhost:8765) │
│ • Interactive timeline scrubber (J / K / Space) │
│ • Line-level crash focus & IDE gutter │
│ • POST /api/replay (In-memory execution in <1ms) │
│ • POST /api/patch (Atomic disk writer with backup) │
└────────────────────────────────────────────────────────┘
Naive instruction-level tracing logs every bytecode or loop iteration, introducing 10x–30x runtime overhead. Rewind instead intercepts function boundaries (call, return, exception):
- On
call: Snapshots argument values at function entry and starts a high-resolution timer (time.perf_counter()). - On
return: Records return values, computes state differences against the prior frame, and records step latency in microseconds. - On
exception: Captures the traceback, exact file and line number, and marks the frame asFAILED.
Complex objects frequently contain nested dictionaries, custom class instances, or circular references (a.child = b; b.parent = a). Rewind's serializer:
- Tracks visited memory addresses via
id(obj)in a set to avoid recursion limits. - Recursively computes structural diffs:
+ Added: New keys introduced in the frame.~ Mutated: Modified values, displayed asprevious_value → new_value.- Removed: Deleted keys.
When testing code changes in the web dashboard, Rewind compiles and executes the modified script in RAM using compile() and exec(), with stdout and stderr redirected to memory buffers (io.StringIO). This provides sub-millisecond validation without creating child OS processes or modifying files on disk.
| Feature | Standard Debugger (pdb, VS Code) |
Mozilla rr |
Rewind |
|---|---|---|---|
| Platform / Language | Python, general | Linux C/C++/Rust | Python / Script Pipelines |
| Direction | Forward-only | Bidirectional | Bidirectional (J / K) |
| State After Crash | Lost on exit | Replayable via GDB | Frozen & visually inspectable |
| State Visibility | Manual variable queries | Memory watchpoints | Automatic visual diffs (+, ~, -) |
| Fix Verification | Re-run process from terminal | Re-run from terminal | In-memory hot replay in 0.14 ms |
| Trace Portability | None | Local machine only | Portable JSON artifact |
| Dependencies | Built-in | Linux kernel counters | Pure standard library (0 dependencies) |
Clone and install in editable mode:
git clone https://github.com/hrinkar01/rewind.git
cd rewind
pip3 install -e .Rewind has zero external dependencies and runs on Python 3.8+ using only standard library modules.
Trace any script with zero code modifications:
rewind run tests/broken_pipeline.py- Intercepts execution and streams stdout/stderr to your terminal.
- Captures fatal exceptions with source context and line attribution.
- Automatically launches the web scrubber at
http://localhost:8765.
You can also run external commands, servers, or build scripts through Rewind:
# Node / Next.js
rewind exec npm run dev
# Go / Rust
rewind exec go run main.go
rewind exec cargo run
# Test suites
rewind exec pytest tests/Run headlessly in CI/CD pipelines (GitHub Actions, GitLab CI):
rewind run --ci tests/broken_pipeline.pyOutputs a structured step summary and exits with code 0 on clean pass, or 1 if an exception occurred.
# Start viewer for an existing trace file
rewind view rewind_trace.json
# Check server status
rewind status
# Stop running Rewind web servers
rewind stopWhen an exception occurs, the web dashboard highlights the failure and positions the editor directly at the offending line:
💥 Crash at Line 38 finalize_invoice() broken_pipeline.py:38 TypeError
ERROR: unsupported operand type(s) for +: 'float' and 'NoneType'
CAUSE: order['tax'] is None (cannot add float + None)
| Key | Action |
|---|---|
J / ← |
Step backward to previous frame |
K / → |
Step forward to next frame |
Space |
Play / Pause continuous execution playback |
Home / End |
Jump to first / last frame |
⌘↵ / Ctrl+Enter |
Replay modified code in in-memory sandbox |
⌘S / Ctrl+S |
Save validated fix to disk (creates .bak backup) |
You can also instrument specific application blocks using the context manager API:
from rewind import Tracer, step
tracer = Tracer(title="Order Processing Pipeline")
# Step 1: Initialize user session
with step("init_session", user_id="usr_102") as state:
state["user"] = "Alice"
state["cart"] = {"items": ["Keyboard"], "subtotal": 120.00}
# Step 2: Apply discount
with step("apply_discount", coupon="SAVE20") as state:
state["cart"]["subtotal"] = 96.00
state["cart"]["discount_applied"] = True
# Step 3: Export trace for web scrubbing
tracer.export("rewind_trace.json")Run the unit tests:
python3 -m unittest discover -s tests -p "test_*.py" -vRan 16 tests in 0.045s
OK
Covers serialization safety (primitives, sets, classes, circular references), diff computation, multithreaded step recording, hot-replay execution, and CLI trace lifecycles.
Distributed under the MIT License. See LICENSE for details.