Metadata-Version: 2.4
Name: rewindex
Version: 0.1.7
Summary: Version control for AI agents. Every change saved automatically. Every mistake undone instantly.
License: Proprietary
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: watchdog<7,>=4.0
Requires-Dist: questionary<3,>=2.0
Requires-Dist: click<9,>=8.0
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: psutil<6,>=5.9
Requires-Dist: rich<15,>=13.0

# Rewindex

![version](https://img.shields.io/badge/version-0.1.7-blue)
![python](https://img.shields.io/badge/python-3.10%2B-blue)
![license](https://img.shields.io/badge/license-proprietary-red)

**Version control for AI agents. Every change saved automatically. Every mistake undone instantly.**

Rewindex runs silently in the background and snapshots every file your AI agent touches. When something goes wrong, rewind any file to any point in time — no commits needed, no manual saves, no lost work.

> Instead of pasting broken code back into the chat, just rewind and tell the agent to try again — in seconds, not minutes.

---

## Table of Contents

- [Why Rewindex](#why-rewindex)
- [How It Works](#how-it-works)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Commands](#commands)
  - [Command Tree](#command-tree)
  - [Setup](#setup)
  - [History](#history)
  - [Snapshots](#snapshots)
  - [Rewind & Restore](#rewind--restore)
  - [Project Management](#project-management)
  - [Maintenance](#maintenance)
- [Configuration](#configuration)
- [Supported AI Agents](#supported-ai-agents)
- [Session Grouping](#session-grouping)
- [Snapshot Notes](#snapshot-notes)
- [Security](#security)
- [How Snapshots Work](#how-snapshots-work)
- [FAQ](#faq)
- [License](#license)

---

## Why Rewindex

When AI agents edit your code, changes happen fast. A single prompt can modify 10 files in seconds. If something goes wrong:

- **Git won't help** — you haven't committed yet
- **Ctrl+Z won't help** — the AI edited files outside your editor
- **File backups won't help** — they're too coarse-grained

Rewindex captures every change the moment it happens. You can see exactly what each agent changed, when, and rewind any file to any previous state.

### Save tokens, not just files

When an AI agent makes a bad change, the typical response is to paste the broken code back into the chat and ask it to fix the problem — burning through context and tokens trying to debug something that was working 30 seconds ago.

With Rewindex, you skip that entirely:

```bash
rewindex rewind --agent claude --last --yes
```

Files are instantly restored to before the agent touched them. Tell the agent "rewound, try again with a different approach" — and you're back to a clean state in seconds, not minutes.

The shorter the feedback loop, the less it costs to course-correct.

## How It Works

1. A background daemon watches your project folder(s)
2. When a file changes, Rewindex hashes it and creates a compressed snapshot
3. Only the delta (diff) is stored — not the entire file
4. An agent detector identifies which AI tool made the change
5. Your AI agent (or you) browses history, views diffs, and rewinds files through the CLI

Everything stays on your machine. No cloud, no account, no telemetry.

## Installation

> **Supported platforms: macOS and Linux only.** Windows is not yet supported.

```bash
# pip
pip install rewindex

# pipx (recommended for CLI tools — keeps dependencies isolated)
pipx install rewindex

# uv
uv tool install rewindex
```

Requires Python 3.10+.

## Quick Start

```bash
# 1. Set up your project (runs once — starts the daemon automatically)
rewindex init
```

`rewindex init` will ask:
- **Project name** — a short name, e.g. `my-app`
- **Folder path** — the folder to watch, e.g. `~/projects/my-app`
- **Start automatically on login?** (**Y** recommended)
  - Y: Rewindex boots with your machine — nothing else to do
  - N: you'll need to run `rewindex start` manually, now and after every reboot

```bash
# 2. Let your AI agent work — Rewindex snapshots every file change silently

# 3. View what happened
rewindex log

# 4. See exactly what changed in a snapshot
rewindex diff [SN0042]

# 5. Restore files to a previous state
rewindex rewind [SN0042]
```


Non-interactive setup (for AI agents):

```bash
rewindex init --project [your-project-name] --folder [/path/to/project]
rewindex start
```

> Non-interactive mode configures autostart automatically — no prompt needed.

## Project Selection

All commands auto-detect the active project from your current working directory. No need to specify `-p` if you're already inside the project folder.

```bash
cd ~/projects/my-app
rewindex snap           # auto-detects my-app
rewindex log            # shows my-app history
rewindex note latest "..." # annotates my-app
```

Use `-p [project-name]` to target a different project regardless of CWD. If you're outside all project folders and have multiple projects, an interactive picker appears.

## Commands

### Command Tree

```
rewindex
├── init                           Set up a project and start the daemon
├── start                          Start the background file watcher
├── stop                           Stop the background file watcher
├── status                         Show daemon state and all project summaries
│
├── log                            History grouped by session (SS001, SS002...)
│   ├── --detail / -d              Individual snapshots instead of sessions
│   ├── --agent / -a [name]        Filter by agent name (e.g. claude)
│   ├── --since / -s [HH:MM]       Show only entries after this time
│   ├── --from / -f [N]            From snapshot #N
│   ├── --to / -t [N]              To snapshot #N
│   └── --limit / -l [N]           Max entries (default: 50)
│
├── diff [SN0042]                  Line-by-line diff for a snapshot
│
├── snap ["message"]               Manually trigger a snapshot now
│
├── rewind [SN0042 | SS003]        Restore files to a previous state
│   ├── [files...]                 Limit rewind to specific file(s)
│   ├── --yes / -y                 Skip confirmation prompt
│   ├── --preview                  Show diff only — do not write files
│   ├── --session [N]              Rewind entire session by number
│   ├── --snap [N]                 Rewind to snapshot by number
│   └── --agent [name] --last      Undo last change by a specific agent
│
├── note [SN0042 | latest] "text"  Add a note to a snapshot
│   └── --edit "text"              Replace existing note
│
├── project                        List all configured projects
│   ├── add [name] [folder]        Add a new project
│   ├── remove [name]              Remove a project (snapshots kept)
│   ├── rename [old] [new]         Rename a project
│   ├── add-folder [name] [path]   Add an extra folder to a project
│   └── remove-folder [name] [path] Remove a folder from a project
│
├── cleanup                        Free disk space
│   ├── --apply                    Actually delete (default is dry run)
│   └── --orphans                  Target unused snapshot directories
│
└── update                         Check version and sync config
    ├── --latest                   Upgrade from PyPI
    └── --sync                     Fill in any missing config defaults
```

> **ID formats** — all commands accept any of these for the same snapshot:
> `SN0042` · `#0042` · `42` — they all mean snapshot 42.
> Sessions: `SS003` · `#SS003` · `3` — they all mean session 3.

---

### Setup

#### `rewindex init`

Sets up Rewindex for a project. Creates the config, registers the folder, starts the daemon, and configures autostart.

```bash
rewindex init
```

Interactive mode asks for:
- **Project name** — a short name, e.g. `my-app`
- **Folder path** — the folder to watch, e.g. `~/projects/my-app`
- **Start automatically on login?** (**Y** recommended)
  - Y: Rewindex boots with your machine — nothing else to do
  - N: you'll need to run `rewindex start` manually, now and after every reboot

For non-interactive use (AI agents or scripts) — autostart is configured automatically:

```bash
rewindex init --project [project-name] --folder [/path/to/project]
```

| Option | What to put here |
|--------|-----------------|
| `--project` | A short name, e.g. `my-app` — used to identify it in all other commands |
| `--folder` | Absolute path to watch, e.g. `~/projects/my-app` |

> Safe to re-run — merges with existing config, never overwrites.

---

#### `rewindex start` / `rewindex stop`

Manually start or stop the background daemon.

```bash
rewindex start    # start watching
rewindex stop     # stop watching
```

> Only needed if you answered N to autostart during `rewindex init`.

Only **one** daemon runs system-wide — it already watches every configured project, so running `rewindex start` a second time is a no-op and prints:

```
Rewindex is already running (PID 12345). It watches all configured projects, so no need to start again.
To restart, run 'rewindex stop' first, then 'rewindex start'.
```

---

#### `rewindex status`

Shows whether the daemon is running, and a summary of every configured project.

```bash
rewindex status
```

Output:
```
Rewindex is running (PID 12345)

  PJ001  my-app
    → ~/projects/my-app
    142 snapshots · 28 files · latest SN0142
    Last activity: 2026-04-15 14:32:05
    Disk usage: 3.2 MB
```

| Line | Meaning |
|------|---------|
| `PJ001` | Project ID — use this with `-p` on any command |
| `142 snapshots · 28 files` | Total snapshots recorded, across how many distinct files |
| `latest SN0142` | The most recent snapshot ID |
| `Last activity` | When the last snapshot was taken |
| `Disk usage` | How much space the snapshots are using |

---

### History

#### `rewindex log`

Shows the snapshot history grouped into sessions. A **session** is a group of snapshots made by the same agent within 20 seconds of each other — typically one "task" the agent performed.

```bash
rewindex log                        # default: session view
rewindex log --detail               # individual snapshots, one per line
```

Session view output:
```
  SS003  SN0042–SN0044  14:30–14:32  Claude Code       3 files
               src/auth.py
               src/middleware.py
               — refactored auth to JWT

  SS002  SN0041         14:15        manual            1 file
               config.py
```

| Column | Meaning |
|--------|---------|
| `SS003` | Session ID — use with `rewindex rewind [SS003]` to restore all files to their state at this session |
| `SN0042–SN0044` | Range of snapshot IDs in this session |
| `14:30–14:32` | Time range when changes happened |
| `Claude Code` | Which agent (or `manual` for changes made outside an agent) |
| `3 files` | How many files were changed in this session |
| `— refactored auth to JWT` | Note attached to one of the snapshots |

**Filtering options:**

```bash
rewindex log --agent [claude]        # only show sessions by a specific agent
                                     # get agent names from the log output above

rewindex log --since "[14:00]"       # only show snapshots after 14:00 today
                                     # also accepts ISO format: 2026-04-15T14:00

rewindex log --from [39] --to [50]   # only show snapshots SN0039 to SN0050
                                     # get SN numbers from any log output

rewindex log --limit [100]           # show up to 100 entries (default: 50)

rewindex log --detail                # one line per snapshot instead of grouped sessions
```

`--detail` output (one line per snapshot):
```
  SN0042  2026-04-15 14:30:05  Claude Code       src/auth.py  — refactored auth
  SN0041  2026-04-15 14:15:22  manual            config.py
```

> Use `--detail` when you want to see exactly which file each snapshot belongs to, or to look up a specific SN ID.

---

#### `rewindex diff [SN0042]`

Shows a line-by-line diff of what changed in a snapshot — what was added, removed, or modified.

```bash
rewindex diff                   # interactive — pick from a list
rewindex diff [SN0044]          # show diff for a specific snapshot
rewindex diff [44]              # plain number works too
```

**Where to get SN0044:** run `rewindex log --detail` and copy the ID from the left column.

---

### Snapshots

#### `rewindex snap ["message"]`

Manually forces a snapshot of all changed files in the project right now, without waiting for the daemon's debounce timer.

```bash
rewindex snap                              # snapshot all changed files immediately
rewindex snap ["before major refactor"]    # same, and attach a message to each snapshot
```

If a file has not changed since the last snapshot, `snap` skips it — but if you provide a message, it attaches that message to the file's latest snapshot anyway.

Output:
```
  SN0043  2026-04-15 14:32:01  src/auth.py  — before major refactor
  SN0044  2026-04-15 14:32:01  src/models.py  (no change)  — before major refactor

Snapshot complete — 1 file(s) recorded.
Message attached to 2 snapshot(s).
```

> **When to use:** run `snap` before a risky operation so you have a clean restore point with a descriptive label. The daemon handles everything else automatically.

---

### Rewind & Restore

#### `rewindex rewind [SN0042 | SS003]`

Restores one or more files to the state captured at the given snapshot or session.

**Step 1 — find what you want to rewind to** using `rewindex log` or `rewindex log --detail`.  
**Step 2 — run rewind** with the ID you found.

```bash
# No argument — opens an interactive picker to choose snapshot and files
rewindex rewind

# Rewind the file(s) associated with snapshot SN0044 back to that state
# (auto-detects SN prefix)
rewindex rewind [SN0044]
rewindex rewind [44]                # same thing — plain number works

# Rewind only one specific file from that snapshot
rewindex rewind [SN0044] [src/auth.py]

# Restore ALL files changed during session SS003 to their state at the end of that session
# (auto-detects SS prefix)
rewindex rewind [SS003]

# Undo all changes by a specific agent — use the agent name shown in `rewindex log`
rewindex rewind --agent [claude] --last   # undo only the most recent change by this agent
rewindex rewind --agent [claude]          # undo all changes by this agent

# Preview what would change before actually writing — safe, read-only
rewindex rewind --preview [SN0044]
```

The `--yes` / `-y` flag skips the confirmation prompt — useful for AI agents or scripts:

```bash
rewindex rewind [SN0044] --yes
rewindex rewind [SS003] --yes
rewindex rewind --agent [claude] --last --yes
```

Output after rewind:
```
  SN0041  2026-04-15 14:30:44  src/auth.py  — before major refactor
  SN0039  2026-04-15 14:29:11  src/models.py

2 file(s) rewound.
```

| Part | Meaning |
|------|---------|
| `SN0041` | The snapshot that was restored (the state the file was rewound to) |
| `14:30:44` | When that snapshot was taken |
| `src/auth.py` | The file that was overwritten |
| `— before major refactor` | Note on that snapshot (if any) |

> **Tip:** use `--preview` first if you're unsure. It shows the diff without modifying any files.

---

#### `rewindex note [SN0042 | latest] "text"`

Attaches a note to a snapshot — useful for documenting what changed and why.

```bash
rewindex note latest "refactored auth to JWT"       # attach to the most recent snapshot
rewindex note [SN0044] "before breaking change"     # attach to a specific snapshot
rewindex note [SN0044] --edit "[corrected note]"    # replace an existing note
```

**Where to get SN0044:** run `rewindex log --detail` and copy the ID from the left column.

`latest` always refers to the single most recent snapshot (one file). If you edited multiple files, use `rewindex log --detail` to find each file's SN ID and annotate them separately.

Notes appear in `rewindex log` output under the session they belong to, and inline in `rewindex rewind` output.

---

### Project Management

#### `rewindex project`

Lists all configured projects with their PJ IDs and folder paths.

```bash
rewindex project
```

Output:
```
  PJ001  my-app      →  ~/projects/my-app
  PJ002  other-app   →  ~/projects/other-app
```

Use the project name (e.g. `my-app`) or PJ ID (e.g. `PJ001`) with `-p` on any command to target a specific project when you're outside the project folder.

---

#### `rewindex project add [name] [folder]`

Registers a new project folder to watch. The daemon picks it up immediately.

```bash
rewindex project add [project-name] [/path/to/folder]
```

| Argument | What to put here |
|----------|-----------------|
| `[project-name]` | A short identifier, e.g. `backend`. No spaces. |
| `[/path/to/folder]` | Absolute or `~`-prefixed path to the folder to watch. |

---

#### `rewindex project remove [name]`

Unregisters a project — Rewindex stops watching it. **Snapshots are kept on disk** until you explicitly clean them up.

```bash
rewindex project remove [project-name]
rewindex project remove [project-name] --yes    # skip confirmation
```

To also delete the snapshot data after removing:
```bash
rewindex cleanup --orphans --apply
```

---

#### `rewindex project rename [old] [new]`

Renames a project. Updates the config file, renames the snapshots directory on disk, and updates all records in the database — everything stays consistent.

```bash
rewindex project rename [old-name] [new-name]
rewindex project rename [old-name] [new-name] --yes   # skip confirmation
```

---

#### `rewindex project add-folder [name] [path]`

Adds a second (or third) folder to an existing project. Useful when your project spans multiple directories.

```bash
rewindex project add-folder [project-name] [/path/to/extra-folder]
```

---

#### `rewindex project remove-folder [name] [path]`

Removes one folder from a multi-folder project without deleting the project entirely.

```bash
rewindex project remove-folder [project-name] [/path/to/folder]
```

---

### Maintenance

#### `rewindex cleanup`

Frees disk space by deleting snapshots that are no longer needed — either because the file is committed to git (so git holds the history) or because the project no longer exists in config.

```bash
rewindex cleanup                       # dry run — shows what would be deleted, no changes
rewindex cleanup --apply               # actually delete safe snapshots
rewindex cleanup --orphans             # show snapshot dirs with no configured project
rewindex cleanup --orphans --apply     # delete those orphaned dirs
```

> Always run without `--apply` first to review what would be deleted.

---

#### `rewindex update`

Checks your installed version and optionally upgrades or fills in missing config fields.

```bash
rewindex update                        # show current version and check for updates
rewindex update --latest               # upgrade to the latest version from PyPI
rewindex update --sync                 # add any new default config keys that are missing
```

> Run `rewindex update --sync` after upgrading to a new version — it adds any new config keys without touching your existing settings.

## Configuration

Config file: `~/.rewindex/.rewindex.config.yaml`

```yaml
projects:
  - name: my-app
    folders:
      - ~/projects/my-app
      - ~/projects/shared-lib

exclude:
  - ".env"
  - ".env.*"
  - "node_modules/"
  - ".git/"
  - "__pycache__/"
  - "venv/"
  - ".venv/"
  - "*.log"
  - "*.tmp"

debounce_seconds: 5.0          # wait before snapshotting (group rapid saves)
session_gap_seconds: 20        # gap threshold for session grouping
```

> `.env` and `.env.*` are in the default exclude list so they're never snapshotted out of the box. Remove them from your `exclude` list if you actually want to track them.

### Security Exclusions (hardcoded, not configurable)

These files are **never** snapshotted, regardless of your config:

- `*.secret`, `credentials`, `credentials.*`
- `id_rsa`, `id_ed25519`, `id_dsa`, `id_ecdsa`, `authorized_keys`
- `*.pem`, `*.key`, `*.p12`, `*.pfx`, `*.cer`, `*.crt`
- `.npmrc`, `.pypirc`, `.netrc`
- `*.password`, `*.passwd`, `*.token`
- `*.kubeconfig`

## Supported AI Agents

Rewindex auto-detects which AI agent is modifying your files:

| Agent | Detection |
|-------|-----------|
| Claude Code | Process name `claude` or node args |
| Cursor | Process name `cursor` |
| Windsurf | Process name `windsurf` |
| Aider | Process name `aider` or python args |
| Codex (OpenAI) | Process name `codex` or node args |
| Zed | Process name `zed` |
| OpenClaw | Process name `openclaw` or node args |
| OpenCode | Process name `opencode` |
| Augment Code | Process name `auggie` |
| Hermes | Process name `hermes` |
| Goose | Process name `goose` |
| Plandex | Process name `plandex` or `pdx` |
| ZeroClaw | Process name `zeroclaw` |
| Kilo | Process name `kilo` or node args |
| Pi | Process name `pi` or node args |
| nanobot | Process name `nanobot` |

If no agent is detected, changes are labeled as `manual`.

## Session Grouping

`rewindex log` groups snapshots into sessions automatically:

- **Same agent + gap ≤ 20 seconds** = same session
- **Different agent** = always a new session

```
  SS003  SN0042–SN0044  14:30–14:32  Claude Code       3 files
               src/auth.py
               src/middleware.py
               models/user.py

  SS002  SN0041         14:15        manual            1 file
               config.py
```

Use `rewindex log --detail` to see individual snapshots.

The threshold is configurable via `session_gap_seconds` in your config file.

## Snapshot Notes

Add context to snapshots for future reference:

```bash
rewindex note latest "refactored auth to use JWT"
rewindex note [SN0042] "before breaking change"
rewindex note [SN0042] --edit "[corrected note]"   # replace existing note
```

Notes appear in log output. Designed for both human and AI agent use — agents can annotate their changes automatically.



### Auto-Trim — stays fast forever

Rewindex keeps your history snappy by pruning itself in the background. When a file builds up a long chain of diffs, the oldest ones are consolidated into a fresh base so reconstruct and rewind stay instant no matter how long you've been working.

1. The oldest diffs are rolled into a new full base
2. Everything before it is cleaned up automatically
3. History continues seamlessly — recent snapshots untouched, disk usage stays lean, and nothing slows down

No configuration, no maintenance — Rewindex just keeps itself light so your day-to-day workflow never feels the weight.


## FAQ

**Q: Does Rewindex modify my files?**
A: Never. It only reads files to create snapshots. The only time it writes to your project folder is when you explicitly run `rewindex rewind`.

**Q: Does it send data anywhere?**
A: No. Everything is stored locally in `~/.rewindex/`. Cloud backup is planned for a future release but is opt-in.

**Q: How much disk space does it use?**
A: Very little. Diffs are compressed and typically 50-500 bytes each. Run `rewindex status` to check, or `rewindex cleanup` to free space.

**Q: Can I use it without AI agents?**
A: Yes. Rewindex snapshots any file change, whether made by an AI agent, your editor, or a script. Manual changes are labeled as `manual`.

**Q: Does it work on Windows?**
A: Not yet. Currently supports Linux and macOS.

## License

Proprietary. See LICENSE for details.
