Metadata-Version: 2.4
Name: autocheckpoint
Version: 0.2.7
Summary: Never lose your code or your project context again. AI Development Continuity tool.
Home-page: https://github.com/epicadidash/talvo-demo
Author: AutoCheckpoint Maintainers
Author-email: maintainers@autocheckpoint.dev
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: watchfiles>=0.21.0
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.7.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: pathspec>=0.12.1
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# AutoCheckpoint

**AI Development Continuity — Never lose your code or context again.**

```
pip install autocheckpoint
```

---

## The Problem

Every developer using AI tools hits this wall:

```
New Claude session      → AI has no idea what you built
Switch to Cursor        → Re-explain everything from scratch
VM deleted              → Code AND context both gone
Restore from git        → No goals, no decisions, no task list
```

AutoCheckpoint solves all three in one tool:

| What | How |
|---|---|
| **Code snapshots** | Auto-saves your project files every time something changes |
| **Context detection** | Reads README, git history, TODO comments, CLAUDE.md, Cursor rules, Antigravity sessions — figures out your goal, focus, decisions, tasks using Gemini AI |
| **Universal AI sync** | Writes that context into `CLAUDE.md`, `.cursorrules`, `.windsurfrules`, `.ai-context.md` — every AI tool picks it up automatically |

---

## Installation

```bash
pip install autocheckpoint
```

Works on Windows, macOS, Linux. No system dependencies.

### Optional: Gemini API key (recommended)

Without this, context detection uses heuristics (README + git log).  
With it, Gemini reads everything and extracts structured context with confidence scores.

```bash
# Windows
set GEMINI_API_KEY=your_key_here

# macOS / Linux
export GEMINI_API_KEY=your_key_here
```

### Optional: rclone (for cloud backup)

Install [rclone](https://rclone.org/install/) to sync snapshots to Google Drive, OneDrive, or Dropbox.

---

## Quickstart

```bash
# 1. Go to your project
cd my-project

# 2. Initialize (asks for backup location, auto-detects context)
autocheckpoint init

# 3. Start the background watcher
autocheckpoint start --background

# 4. Work normally — AutoCheckpoint watches silently

# 5. Restore anywhere (new machine, new folder, deleted VM)
autocheckpoint restore
```

---

## How It Works — Full Lifecycle

### Step 1: `autocheckpoint init`

1. Asks where to store backups (local folder, Google Drive, OneDrive, Dropbox)
2. Creates `.autocheckpointignore` with sensible defaults
3. Scans your project — README, git log, CLAUDE.md, `.cursorrules`, TODO comments, Antigravity sessions
4. Calls Gemini to extract goal / focus / decisions / tasks with **confidence scores**
5. Writes high-confidence facts (≥65%) into `CLAUDE.md`, `.cursorrules`, `.windsurfrules`, `.ai-context.md`
6. Optionally starts the background watcher

### Step 2: Background watcher

The watcher polls every 1.5 seconds for file changes.

```
File changed
    ↓
Wait 2s debounce (avoids snapshots mid-save)
    ↓
Cooldown passed? (default: 5 min)
    ↓
Save snapshot → backup/project/snapshot_2026-06-19_11-28-41.tar.gz
    ↓
Every 10 snapshots OR 30 min → re-scan context
    ↓
Update CLAUDE.md / .cursorrules / .windsurfrules
```

### Step 3: Snapshots

Each snapshot is a `.tar.gz` archive containing:

- All tracked project files (respects `.autocheckpointignore`)
- `context.yaml` and `handoff.md` — **always included**, even if `.autocheckpoint/` is in the ignore list
- **Never includes**: the backup directory itself, even if it lives inside the project folder

### Step 4: Restore

```
autocheckpoint restore
    ↓
Select backup location
    ↓
Select project
    ↓
Select snapshot (time-stamped list)
    ↓
Clean target directory (non-ignored files removed)
    ↓
Extract snapshot files
    ↓
Regenerate CLAUDE.md / .cursorrules / .windsurfrules from context.yaml
    ↓
Done — open in any AI tool, it already knows your context
```

---

## All Commands

### `autocheckpoint init`

Initialize a project. Run once per project.

```bash
autocheckpoint init
autocheckpoint init --backup-path ~/my-backups   # skip the prompt
```

### `autocheckpoint start`

Start the file watcher.

```bash
autocheckpoint start                    # foreground (live log)
autocheckpoint start --background       # detached process
autocheckpoint start --interval 2       # snapshot every 2 minutes
```

Logs go to `.autocheckpoint/watcher.log` in background mode.

### `autocheckpoint stop`

```bash
autocheckpoint stop
```

### `autocheckpoint status`

Show watcher state, snapshot count, last snapshot time, project context summary.

```bash
autocheckpoint status
```

### `autocheckpoint restore`

Restore a snapshot. Works even if the project was never initialized here.

```bash
autocheckpoint restore
```

Prompts for backup location if not initialized. Lists all available projects and recovery points. After restore, all AI tool files are regenerated automatically.

### `autocheckpoint handoff`

Generate a full project state summary — goal, focus, decisions, constraints, tasks, recent git changes.

```bash
autocheckpoint handoff             # rich terminal display
autocheckpoint handoff --markdown  # raw markdown to stdout (paste into any AI)
```

Saves to `.autocheckpoint/handoff.md` — bundled in the next snapshot.

### `autocheckpoint explain`

Show exactly where every auto-detected fact came from and its confidence score.

```bash
autocheckpoint explain
```

Example output:

```
Goal  85%
  "Build AutoCheckpoint — AI development continuity tool"
  Inferred from:
    • README.md
    • package.json description

Current Focus  70%
  "Fixing restore bug and adding universal AI tool sync"
  Inferred from:
    • git: last 3 commits
    • TODO in restore.py:34

Task 1  62%  ← below threshold, not written to tool files
  "Add cloud backup UI"
  Inferred from:
    • auth.py:88 TODO comment
```

### `autocheckpoint connect`

Connect a cloud storage provider via rclone.

```bash
autocheckpoint connect gdrive
autocheckpoint connect onedrive
autocheckpoint connect dropbox
```

### Context subcommands

These are only needed to manually override auto-detected values. The system works without them.

```bash
autocheckpoint context show            # display full context
autocheckpoint context refresh         # re-scan with Gemini, merge new facts
autocheckpoint context set-intent      # manually set project goal
autocheckpoint context set-focus       # manually set current focus
autocheckpoint context add-decision    # manually record a decision
autocheckpoint context add-constraint  # manually record a constraint
autocheckpoint context add-task        # manually add a task
autocheckpoint context done-task       # mark a task done
autocheckpoint context add-session     # record a session summary
autocheckpoint context summarize       # interactive wizard for all fields
```

---

## Context System

Context is stored in `.autocheckpoint/context.yaml`.

### Confirmed fields (written to AI tool files)

```yaml
intent:             "What this project builds — one sentence"
current_focus:      "What is actively being worked on right now"
decisions:          [{text, recorded_at}, ...]
known_constraints:  [{text, recorded_at}, ...]
tasks:              [{text, status: todo|done, recorded_at}, ...]
session_summary:    "Latest session summary"
```

### `_detected` (AI raw output — never edit this)

```yaml
_detected:
  intent:
    value:      "Build AutoCheckpoint..."
    confidence: 0.85
    sources:    ["README.md", "package.json"]
  decisions:
    - value:      "Use tar.gz for snapshots"
      confidence: 0.72
      sources:    ["git: commit a1b2c3 Add snapshot impl"]
```

### What signals are scanned

| Source | What's extracted |
|---|---|
| `README.md` | Project description, goal |
| `CLAUDE.md` | Claude Code instructions, architectural decisions |
| `.cursorrules` | Cursor rules and constraints |
| `.cursor/chat/*.json` | Recent Cursor conversations |
| `package.json` / `pyproject.toml` / `Cargo.toml` | Project name, description |
| `git log` (last 30) | What was recently worked on |
| TODO / FIXME / HACK comments | Open tasks |
| `~/.gemini/antigravity-ide/brain/` | Recent Antigravity AI sessions |
| `.env.example` / `.env.sample` | Service names (never values) |

---

## Universal AI Tool Sync

Every time context is saved, these files are written automatically:

| File | AI Tool |
|---|---|
| `CLAUDE.md` | Claude Code (Anthropic) |
| `.cursorrules` | Cursor |
| `.windsurfrules` | Windsurf |
| `.ai-context.md` | Universal fallback |

Each file gets a clearly-marked section that is replaced on every update. Your existing content in the file is untouched outside the markers.

```markdown
<!-- autocheckpoint:start -->
## Project Context (AutoCheckpoint)

**Goal:** Build AutoCheckpoint — AI development continuity tool

**Current Focus:** Universal AI tool sync feature

**Key Decisions:**
- Use tar.gz for snapshots
- Confidence threshold 65% for writing to tool files

**Open Tasks:**
- [ ] Add Antigravity in-project context file support

**Last Session:** Fixed restore bug, added confidence scoring
<!-- autocheckpoint:end -->
```

These files are regular project files — they're included in every snapshot. When you restore on a new machine and open in any AI tool, it reads its native file and immediately knows your full context.

---

## Confidence & Trust

The auto-detector assigns a confidence score to every fact it finds. Only facts at **≥ 65% confidence** are written into tool files.

| Confidence | Behavior |
|---|---|
| ≥ 80% | Written — high confidence, multiple sources |
| 65–79% | Written — acceptable confidence |
| < 65% | Stored in `_detected` only — not written to tool files |

**Why this matters:**

Without confidence gating, contradictory signals cause hallucinations:
- README says "auth service"
- Recent commits say "billing module"  
- TODO says "migrate database"
- AI invents: "enterprise payment platform" ← nobody decided this

With confidence gating, contradictory signals produce a low score and stay invisible to AI tools until you confirm them manually.

Run `autocheckpoint explain` to see the reasoning behind every fact and decide whether to trust it.

---

## Restore Workflow (Full Example)

Scenario: VM deleted, restoring on a new machine.

```bash
# On the new machine
cd ~/new-project-folder
autocheckpoint restore

# Output:
# Project is not initialized in this directory.
#
# Where are the backups stored?
# 1. Local Only
# 2. Google Drive
# 3. OneDrive
# 4. Dropbox
#
# Select option: 1
# Enter local backup path: ~/autocheckpoint_backups
#
# Available projects:
# 1) my-project
#
# Available recovery points:
# 1) 2026-06-19 11:28 AM  ← most recent
# 2) 2026-06-19 10:45 AM
# ...
#
# Select version: 1
# Restoring snapshot...
# + Re-initialized AutoCheckpoint config
# + AI tool context files synced (CLAUDE.md, .cursorrules, .windsurfrules)
# + Restore complete!
```

After restore, your folder contains:

- All code files as of that snapshot
- `CLAUDE.md` — Claude Code immediately knows your goal and context
- `.cursorrules` — Cursor immediately knows your goal and context
- `.windsurfrules` — Windsurf immediately knows your goal and context
- `.autocheckpoint/context.yaml` — full structured context
- `.autocheckpoint/handoff.md` — human-readable summary to paste anywhere

---

## Cloud Sync

```bash
# One-time setup (opens browser for OAuth)
autocheckpoint connect gdrive

# Then during init, choose Google Drive
autocheckpoint init
# → Select: 2. Google Drive
# → Follow rclone OAuth flow
# → Snapshots now sync automatically after every save
```

On a new machine, select the cloud provider during restore — the snapshot is downloaded on demand.

---

## Ignore Patterns

Edit `.autocheckpointignore` in your project root. Uses gitignore-style syntax.

**Default exclusions (always applied):**

```
.git/
node_modules/
venv/
.venv/
__pycache__/
dist/
build/
.autocheckpoint/
*.pyc
*.pyo
*.pyd
.DS_Store
```

**Adding your own:**

```gitignore
# .autocheckpointignore
*.log
*.tmp
uploads/
data/raw/
```

> **Note:** The backup directory is always excluded from snapshots even if it lives inside the project folder and is not listed in `.autocheckpointignore`. This prevents snapshot archives from being bundled inside other snapshots.

---

## Configuration

Stored in `.autocheckpoint/autocheckpoint.yaml`:

```yaml
backup_location: ~/autocheckpoint_backups
project_name: my-project
interval_minutes: 5.0
```

| Field | Default | Description |
|---|---|---|
| `backup_location` | set during init | Where snapshot `.tar.gz` files are stored |
| `project_name` | folder name | Subdirectory name inside `backup_location` |
| `interval_minutes` | `5.0` | Minimum cooldown between snapshots |

Override interval at runtime:

```bash
autocheckpoint start --interval 2   # snapshot every 2 minutes
```

---

## The Demo Scenario

**Day 1 — Claude Code**  
Run `autocheckpoint init`. Reads README + git history. Detects goal at 85% confidence. Writes it into `CLAUDE.md`. Work. Snapshots every 5 minutes.

**Day 2 — Switch to Cursor**  
Open same project in Cursor. It reads `.cursorrules`. Cursor already knows your goal, current focus, key decisions. Zero re-explaining.

**Day 3 — VM deleted**  
Cloud VM is gone. Snapshots are on Google Drive. Context is in those snapshots.

**Day 4 — New machine, Windsurf**  
`autocheckpoint restore` → select Google Drive → select project → select snapshot. All code restored. `.windsurfrules` regenerated from saved `context.yaml`. Open Windsurf. It reads `.windsurfrules`. Windsurf immediately sees: Goal, Open Tasks, Recent Decisions, Known Constraints. Continue exactly where you left off.

---

## Project Structure

```
your-project/
├── .autocheckpoint/
│   ├── autocheckpoint.yaml   ← config
│   ├── context.yaml          ← goal, focus, decisions, tasks, _detected
│   ├── handoff.md            ← generated summary (bundled in snapshots)
│   └── watcher.log           ← background watcher logs
├── .autocheckpointignore     ← ignore patterns
├── CLAUDE.md                 ← auto-written (Claude Code context)
├── .cursorrules              ← auto-written (Cursor context)
├── .windsurfrules            ← auto-written (Windsurf context)
├── .ai-context.md            ← auto-written (universal fallback)
└── your code...

backup-location/
└── your-project/
    ├── snapshot_2026-06-19_11-28-41.tar.gz
    ├── snapshot_2026-06-19_11-33-12.tar.gz
    └── ...
```

---

## License

MIT
