Agent-Checkpoint: A zero-dependency pre-edit snapshot & SemVer audit trail for Cursor

Showcase Built for Cursor
,
1

Hey everyone! :waving_hand:

Like many of you, I rely heavily on Cursor Composer / Agent mode for daily development. But during fast multi-turn prompt sessions, I kept running into a familiar headache:

The problem:
Cursor Agent occasionally hallucinates, rewrites half of a working module, or overwrites custom logic before you get a chance to inspect it. While Cursor has a built-in checkpoint feature, once you accept an edit and run 3–4 more prompts, cleanly rolling back just one specific file without wiping unrelated good progress across your git tree can be tricky. Furthermore, teammates pulling the code have zero visibility into what the AI modified and why.

To solve this, I built Agent-Checkpoint — an open-source, zero-dependency provenance protocol that runs directly through your .cursorrules.

How It Works in Cursor

Whenever Cursor Agent modifies an existing file in your project, it automatically adheres to a 3-step workflow:

  1. Pre-Edit Snapshot: Before touching any file, it creates a pristine copy at .snapshots/<filename>_v<OLD_VERSION>.<ext>.
  2. Semantic Impact Triage: Cursor categorizes its own changes into prompt-level SemVer:
    • MAJOR: Architectural / breaking interface shift
    • MINOR: New additive feature or non-breaking module
    • PATCH: Bugfix, refactoring, or typo fix
  3. Dual-Ledger Audit Trail:
    • .snapshots/manifest.json: A compact machine index for fast semantic rollback and retrieval.
    • REVISION_LOG.md: A human-readable changelog recording exact lines modified, semantic classification, and rationale.

Quick 30-Second Setup in Cursor

You don’t need any Node packages, Python scripts, or background daemons. Simply copy the ready-to-use adapter rule into your .cursorrules:

:backhand_index_pointing_right: Check out the Cursor Adapter here.

Then, just prompt Cursor as normal! When you ask Cursor to refactor or update a file, it will automatically snapshot the prior state, triage the SemVer change, and append an entry to your REVISION_LOG.md.

Benchmarks & Safety

  • Storage Friendly: Binaries and files > 1 MB are excluded by policy. Active daily usage only generates ~15–50 MB/month of plaintext snapshots.
  • Works out-of-the-box with Claude 3.5/3.7 Sonnet, GPT-4o, and Gemini models inside Cursor.

Looking for Your Feedback!

Since this is completely open-source (MIT), I’d love to hear how fellow Cursor power users feel about this:

  • How do you currently handle rapid rollbacks when Composer touches multiple files?
  • What edge cases would you like to see covered in the protocol?

Feedback and PRs are very welcome! :star:
GitHub: https://github.com/ainullm/agent-checkpoint