rewind-ai 0.1.0

Automatic session checkpoints for AI coding agents. Undo just what went wrong.

⏪ 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.

---

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

pip install rewind-ai

Start the watcher (add to your shell profile or run once per project):

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)

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

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

---

_{Built because every developer using AI coding agents has had the moment: "wait, what did it just do to all my files?"}