Rewind

Time-travel debugging for Python.

Record a program once and inspect its execution history frame by frame. Navigate backward and forward through runtime state, compare snapshots, and locate bugs with precision.

---

Overview

Rewind is a Python time-travel debugger built for developers who want deeper visibility into program execution without modifying application code.

Instead of repeatedly adding print statements or restarting a debugger session, Rewind records execution state once and allows deterministic replay afterward.

Designed for debugging logic errors, state mutations, unexpected variable changes, and difficult-to-reproduce bugs.

---

Features

• Time-travel navigation across recorded execution frames
• Interactive terminal UI with keyboard-driven controls
• Frame-to-frame state diffing
• Variable history search across the entire execution timeline
• SQLite-based trace storage
• Zero code modifications required
• CLI and Python API support
• Lightweight recording format with compression

---

Installation

Requires Python 3.9 or newer.

pip install rewind-debugger

---

Quick Start

Record a program

from rewind import Recorder

recorder = Recorder("trace.db")

recorder.start()

result = buggy_function()

recorder.stop()

Replay execution

rewind replay trace.db

Use the arrow keys to move through execution history frame by frame.

---

Example

Debugging an incorrect discount calculation

from rewind import Recorder

def buggy_calculator(prices, discount):
    total = 0

    for price in prices:
        total += price * discount  # Incorrect logic

    return total


recorder = Recorder("bug.trace")

recorder.start()

result = buggy_calculator([100, 200, 300], 0.1)

print(result)

recorder.stop()

Replay the trace:

rewind replay bug.trace

Navigate through frames to inspect how total changes during execution and identify the faulty calculation.

---

Command Line Interface

Record a Python script

rewind record <script> -o <trace>

Replay a trace

rewind replay <trace>

Compare two execution frames

rewind diff <trace> <frame_a> <frame_b>

Search variable history

rewind search <trace> <variable_name>

Show version information

rewind info

---

Architecture

Rewind is built on top of Python's sys.settrace() API.

Recording Pipeline

1. Hook into the Python interpreter
2. Capture execution events line by line
3. Serialize local execution state
4. Compress and persist snapshots into SQLite
5. Replay snapshots through the debugger UI

---

Performance

Typical recording overhead:

• 2–5× runtime overhead for pure Python workloads
• Approximately 1 KB trace size per 100 executed lines

Performance depends on:

• Variable size
• Serialization complexity
• Frequency of executed lines
• Amount of captured state

---

Limitations

Current limitations include:

• Only the main thread is recorded
• Async support is partial
• Some objects cannot be serialized directly
• Large traces may be generated for long-running programs
• Not intended for production observability

Unsupported objects are represented as lightweight type placeholders during replay.

---

Development

Clone the repository

git clone https://github.com/haianhace123/rewind.git

cd rewind

Install development dependencies

pip install -e .[dev]

Run tests

pytest tests/ -v

Run formatters and type checks

black rewind/

isort rewind/

mypy rewind/

---

Documentation

Detailed documentation is available in:

docs/user_guide.md

Topics include:

• Recording via API and CLI
• Interactive debugger navigation
• Diffing execution state
• Variable search
• Internal architecture
• Troubleshooting

---

Roadmap

Planned improvements:

• Multi-thread recording
• Better async support
• Remote trace inspection
• Web-based replay interface
• Function-level timeline visualization
• Incremental snapshot optimization

---

Contributing

Contributions, bug reports, and feature requests are welcome.

Please open an issue before submitting major architectural changes.

---

License

MIT License

---

Links

• Repository: https://github.com/haianhace123/rewind
• Issues: https://github.com/haianhace123/rewind/issues