Metadata-Version: 2.4
Name: rewind-ai
Version: 0.1.0
Summary: Automatic session checkpoints for AI coding agents. Undo just what went wrong.
Author: Daksh Gulecha
License: MIT
Project-URL: Homepage, https://github.com/dakshgulecha/rewind-ai
Project-URL: Issues, https://github.com/dakshgulecha/rewind-ai/issues
Keywords: ai,claude,cursor,copilot,git,undo,checkpoint,agent
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Software Development :: Version Control
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: watchdog>=4.0.0
Requires-Dist: gitpython>=3.1.40
Requires-Dist: click>=8.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: psutil>=5.9.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

<div align="center">

# ⏪ rewind

**Automatic session checkpoints for AI coding agents.**  
When Claude Code, Cursor, or Copilot goes in the wrong direction, undo just the part that went wrong.

[![PyPI version](https://img.shields.io/pypi/v/rewind-ai.svg)](https://pypi.org/project/rewind-ai/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Tests](https://github.com/rewind-ai/rewind/actions/workflows/test.yml/badge.svg)](https://github.com/rewind-ai/rewind/actions)

</div>

---

## The problem

You run Claude Code to "add authentication." It works for 10 minutes and modifies 14 files. Somewhere around file 11, it went in the wrong direction. Your options:

- `git checkout .` — undo **everything**, including the 10 good minutes
- Manually revert specific files — takes longer than the agent session did
- Ask the agent to undo it — now you're debugging an agent debugging itself

There is no good option. Until now.

---

## How rewind works

Run `rewind watch &` once. Forget about it.

Whenever rewind detects a **write burst** — multiple files changing within a few seconds, the signature of an AI agent actively writing code — it silently snapshots the working tree into a lightweight git commit on a shadow branch. Your real git history is never touched.

When something goes wrong:

```
$ rewind list

Session checkpoints  (5 total)

  #  When     Label                        Changes       Trigger  Agent
  4  2m ago   Modified routes, middleware  ~4 modified   burst    Claude Code
  3  8m ago   Modified auth, user model    ~6 modified   burst    Claude Code  ← went wrong here
  2  14m ago  Added auth module            +3 added      burst    Claude Code
  1  19m ago  Modified package.json        ~1 modified   burst    Claude Code
  0  22m ago  Initial state                +1 added      manual

$ rewind diff 3          # see exactly what changed
$ rewind jump 2          # restore to the last known good state
```

`rewind jump 2` restores your working tree to checkpoint 2. Your git log is unchanged. Your HEAD is unchanged. You get back 12 minutes of good work and lose only the 2 minutes that went wrong.

---

## Install

```bash
pip install rewind-ai
```

**Start the watcher** (add to your shell profile or run once per project):
```bash
rewind watch &
```

That's it. rewind now silently checkpoints your working tree whenever it detects AI agent activity.

---

## Commands

```
rewind watch          Start the background watcher (auto-checkpoints on write bursts)
rewind stop           Stop the watcher
rewind status         Show watcher status + checkpoint count

rewind list           List all checkpoints for the current session
rewind diff [N]       Show diff at checkpoint N  (default: most recent)
rewind jump N         Restore working tree to checkpoint N
rewind branch N       Create a git branch at checkpoint N (non-destructive)

rewind snap           Create a manual checkpoint right now
rewind clear          Delete all checkpoints for this session
rewind install        Install as a git hook (auto-starts on repo entry)
```

---

## How checkpoints work (under the hood)

rewind never writes to your git history. Each checkpoint is:

1. A **git tree object** — a snapshot of your working tree, including untracked files
2. A **shadow commit** referenced by `refs/rewind/TIMESTAMP`
3. Stored in your `.git` directory. Invisible to `git log`, `git status`, and `git push`. Visible to `git log --all` and GUI clients that enumerate all refs — run `rewind clear` after a session to remove them if needed.

Checkpoints are deduplicated by tree SHA — if nothing changed since the last checkpoint, no new one is created. When you run `rewind jump N`, it does a `git checkout <shadow-commit> -- .` — restoring the working tree without touching HEAD or your branch.

**Storage**: A typical session of 50 checkpoints uses ~2-5MB in `.git/objects`. Run `rewind clear` to reclaim it.

---

## Detecting write bursts

rewind identifies AI agent sessions by monitoring for **write bursts**: 2+ files changing within 3 seconds of each other. This is the temporal signature of a code generation agent writing an entire module at once (as opposed to a human who types one file at a time).

Write bursts to high-value files — `package.json`, `requirements.txt`, `CLAUDE.md`, `AGENTS.md`, `.cursorrules` — trigger an **immediate** checkpoint, because these files changing means something significant happened.

---

## Agent self-modification detection

rewind immediately checkpoints (and logs a warning) when an AI agent modifies its own instruction files:

```
⚠  rewind: CLAUDE.md was modified by an active write burst.
   AI agents modifying their own instruction files is a known risk.
   Checkpoint #7 captured the state before this change.
   Run `rewind diff 7` to review.
```

Files watched: `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.github/copilot-instructions.md`, `GEMINI.md`

---

## Works with every AI coding agent

rewind watches the filesystem — it doesn't integrate with any specific tool. It works automatically with:

- **Claude Code** (Anthropic)
- **Cursor** (Anysphere)
- **GitHub Copilot Workspace**
- **Aider**
- **OpenHands / Devin**
- Any agent that writes to your filesystem

---

## Global install (watch all repos automatically)

```bash
rewind install --global
```

This installs a `post-checkout` hook into your global git hooks directory. Every time you `cd` into a git repo (via a shell that runs `git checkout`), the watcher starts automatically.

---

## FAQ

**Does this slow down my editor or agent?**  
No. The watcher runs in a separate process and only creates checkpoints after a write burst completes (3-second quiet window). The `git write-tree` operation is typically <50ms even on large repos.

**Does this interfere with my git history?**  
`git log`, `git status`, and `git push` are all clean — shadow commits are invisible to them. `git log --all` and GUI clients that enumerate all refs (GitLens, Sourcetree, Fork) will show them, because `--all` includes `refs/rewind/*`. If your GUI is noisy, run `rewind clear` at the end of each session to remove the refs, or configure your GUI to hide refs matching `refs/rewind/*`.

**What if I push to remote?**  
The shadow refs are local-only. `git push` will not push them unless you explicitly specify `refs/rewind/*`.

**Can I use this on a repo with no commits yet?**  
Yes. rewind handles empty repos correctly.

**Is my code leaving my machine?**  
No. rewind is entirely local. No telemetry, no network calls, no cloud sync. It's just a Python daemon writing to your `.git` directory.

---

## Why not just commit more often?

Committing often is good practice, but:

1. Mid-session commits pollute your git history with half-finished states
2. You still can't restore to "between commits" — only to full commit boundaries
3. You have to remember to do it; rewind is automatic
4. A commit doesn't know which logical step the agent was in the middle of

---

## Contributing

```bash
git clone https://github.com/rewind-ai/rewind
cd rewind
pip install -e ".[dev]"
pytest
```

Issues and PRs welcome. The codebase is small and documented.

---

## License

MIT

---

<div align="center">
<sub>Built because every developer using AI coding agents has had the moment: <i>"wait, what did it just do to all my files?"</i></sub>
</div>
