agent-checkpoint
Skill3 starsChanged 39 days agoMITView on GitHub
Ultra-efficient, zero-data-loss pre-edit snapshotting, SemVer classification, and token-optimized dual-ledger audit trail (v2.0) for autonomous AI coding agents. Triggers on: agent-checkpoint, checkpoint, snapshot, audit trail, versioning, edit file, refactor, trackback, history, revision log, rollback, diff version.
2 other projects use a version of this.
Adopted by
Most recently taken up by
- NexaiGuy/nex-ai-skillstheir own version, first seen Nov 8, 2026
- hwl668/Agentcheckpointtheir own version, first seen Oct 5, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- hwl668/Agentcheckpoint★ 2same name
- NexaiGuy/nex-ai-skills★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository3 other files it gives its agents.
- adapters/AGENTS.mdAGENTS.md
- adapters/CLAUDE.mdCLAUDE.md
- adapters/copilot-instructions.mdCopilot instructions
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 3 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Zero Data Loss (Pre-Edit Archiving): Never modify, refactor, or overwrite an existing file without archiving its exact prior state.
- Very specific: line 18
Every tracked file receives its own isolated directory inside .snapshots/ matching its relative project path:
- Very specific: line 63
If bucket or file does not exist: treat as initial version (v1.0.0).
- Very specific: line 64
If exists: read latest version from the local manifest.json (< 40 tokens).
- Very specific: line 72
Ensure directory .snapshots/<filepath>/ exists.
- Distinctive: line 95
When requested to review or compare past revisions:
- Very specific: line 96
Read .snapshots/<filepath>/manifest.json to identify available snapshot versions.
- Distinctive: line 104
When requested to revert or restore an earlier version:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Agent-Checkpoint Protocol (v2.0 Turbo)
A universal, zero-dependency safety and provenance protocol for autonomous AI coding and research agents, optimized for minimum token consumption and clean hierarchical storage.
Core Directives
- Zero Data Loss (Pre-Edit Archiving): Never modify, refactor, or overwrite an existing file without archiving its exact prior state.
- Hierarchical File Bucketing (Clean Storage):
Every tracked file receives its own isolated directory inside
.snapshots/matching its relative project path:.snapshots/<relative_filepath>/ ├── manifest.json # Sharded local index (< 40 tokens read) ├── v1.0.0.<ext> # Pristine pre-edit snapshot └── v1.1.0.<ext> - Sliding Window Retention ($K = 5$ Versions Max):
To strictly bound disk space, each file bucket retains at most 5 latest snapshot versions. When creating version 6, the agent automatically prunes the oldest physical snapshot file and updates the bucket's
manifest.json. - Token-Optimized Dual-Ledger Synchronization:
- Sharded Local Index (
.snapshots/<filepath>/manifest.json): AI reads only this file's version state ($O(1)$ token overhead: ~30–50 tokens), avoiding global scans. - Micro-Changelog Stream (
REVISION_LOG.md): Append-only compact table stream. Never re-read previous log history into context.
- Sharded Local Index (
- Universal Scope & Guardrails:
- Full text/code coverage across 100+ extensions (
.py,.ts,.go,.rs,.cpp,.md,.json,.yaml, etc.). - Tabular files (
.csv,.tsv,.jsonl) are snapshotted ONLY if $\le 1\text{ MB}$. Files $> 1\text{ MB}$ log metadata only. - Strictly exclude binary models (
.pt,.onnx,.safetensors), archives (.zip), and caches (node_modules/,venv/,__pycache__/,.git/).
- Full text/code coverage across 100+ extensions (
Standard Directory Layout
[Project_Root]/
├── .snapshots/ # Historical snapshots directory
│ ├── auth_service.py/ # Isolated bucket per file
│ │ ├── manifest.json # Local version registry (< 40 tokens)
│ │ ├── v1.0.0.py # Archived pre-edit snapshot
│ │ └── v1.1.0.py
│ └── src/routes/api.ts/ # Preserves nested structure
│ ├── manifest.json
│ └── v1.0.0.ts
├── REVISION_LOG.md # Append-only compact Markdown table
├── auth_service.py # Active working file
└── src/routes/api.tsOperating Procedures (SOP)
Workflow 1: File Modification & Checkpointing (Fast-Path)
Whenever instructed to modify, refactor, or update an existing file:
- Step 1: Check Local Bucket (
.snapshots/<filepath>/manifest.json)- If bucket or file does not exist: treat as initial version (
v1.0.0). - If exists: read latest version from the local
manifest.json(< 40 tokens).
- If bucket or file does not exist: treat as initial version (
- Step 2: Classify SemVer Impact
- MAJOR: Breaking architectural shift, interface overhaul.
- MINOR: Additive features, new endpoints/functions.
- PATCH: Bug fix, refactor, parameter tuning, typo.
- Step 3: Capture Pre-Edit Snapshot & Apply Retention ($K \le 5$)
- Ensure directory
.snapshots/<filepath>/exists. - Copy current active file to
.snapshots/<filepath>/v<OLD_VERSION>.<ext>. - Sliding Window Check: If total snapshot files in bucket $> 5$, delete the oldest snapshot.
- Ensure directory
- Step 4: Apply Modification to Active File
- Apply user's requested edit on the active file.
- Step 5: Synchronize Dual-Ledger (Micro-Log Stream)
- Update
.snapshots/<filepath>/manifest.json:[ {"version": "v1.1.0", "snapshot": "v1.0.0.py", "impact": "MINOR", "ts": "2026-10-07T03:45:00+07:00", "summary": "Added JWT refresh token"} ] - Append 1 line to
REVISION_LOG.mdwithout reading previous entries:| 2026-10-07 03:45 | v1.1.0 | MINOR | auth_service.py | v1.0.0.py | Added JWT refresh token |
- Update
Workflow 2: Deep Trackback & Semantic Diff
When requested to review or compare past revisions:
- Read
.snapshots/<filepath>/manifest.jsonto identify available snapshot versions. - Load target snapshot (e.g.
.snapshots/<filepath>/v1.0.0.<ext>) and active file. - Present concise Before vs After comparison highlighting algorithmic or interface changes.
Workflow 3: Instant Rollback / Recovery
When requested to revert or restore an earlier version:
- Locate target snapshot in
.snapshots/<filepath>/v<TARGET_VERSION>.<ext>. - Take safety snapshot of the current state (ensuring work-in-progress is never lost).
- Overwrite active file with content from the snapshot.
- Append 1-line rollback event to
REVISION_LOG.md.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

