autocheckpoint 0.3.0

Never lose your code or your project context again. AI Development Continuity tool.

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

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.

# Windows
set GEMINI_API_KEY=your_key_here

# macOS / Linux
export GEMINI_API_KEY=your_key_here

Optional: rclone (for cloud backup)

Install rclone to sync snapshots to Google Drive, OneDrive, or Dropbox.

---

Quickstart

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

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

autocheckpoint start

Start the file watcher.

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

autocheckpoint stop

autocheckpoint status

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

autocheckpoint status

autocheckpoint restore

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

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.

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.

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.

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.

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)

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)

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

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

# 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

# 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:

# .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:

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:

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