I Built ckpt: Automatic Checkpoints for AI Coding Sessions

AI agents don't have Ctrl+Z.

When they break your code, they don't undo. They re-read every file, reason about what went wrong, rewrite from scratch — burning tokens on code they already had right. Sometimes the "fix" breaks something else. And the cycle repeats.

I got tired of watching this happen, so I built ckpt.

What is ckpt?

ckpt is a CLI tool that runs in the background and auto-snapshots every change your AI coding agent makes. You get a full timeline of every step, and you can restore to any point instantly.

ckpt watch        # start watching — auto-snapshots every AI change
# ... let your agent work ...
ckpt steps        # see what happened, step by step
ckpt restore 3    # go back to step 3
ckpt end          # squash into one clean git commit

It's just git under the hood — hidden branch, real commits, squash when done. No new format, no database.

The Problem

AI agents edit your code in rapid bursts — 5, 10, 20 files at once. When something breaks, you have two bad options:

1. Undo everything — lose all the good changes too
2. Manually figure out which change broke things — painful and slow

Every error-fix cycle where the agent re-reads and rewrites costs 500-2000 tokens just to get back to where you were. With ckpt, ckpt restore 3 takes milliseconds and costs zero tokens.

Why Not Just Use IDE Checkpoints?

Cursor has timeline. Kiro has revert. But there are key differences:

The AI agent can operate ckpt — not just you. IDE checkpoints are buttons in a UI. The agent can't click them. With ckpt, the agent itself runs ckpt restore 3. It becomes self-correcting with no human in the loop.

Terminal agents have nothing. Claude Code, Codex, Aider — zero checkpoint support. ckpt is the only checkpoint system that works for terminal-based agents.

Branching. ckpt try approach-a -r 2 saves current work, goes back to step 2, and lets the agent try a completely different approach. Then ckpt trydiff approach-a compares the two. No IDE has this.

Persistent history. IDE checkpoints disappear when you close the session. ckpt log keeps every session permanently.

Quick Start

npm install -g @mohshomis/ckpt

Add this to your AI agent's system prompt:

Run ckpt watch before starting work. If something breaks, run ckpt restore <step> instead of manually rewriting. When done, run ckpt end.

Works With Everything

Kiro, Cursor, Claude Code, OpenAI Codex, GitHub Copilot, Windsurf, Aider — any agent that can run shell commands. It's just a CLI.

---

The repo is open source (MIT). Would love feedback — what's missing? What would make this more useful for your workflow?

mohshomis / ckpt

Automatic checkpoints for AI coding sessions. Per-step undo, branching, and restore — on top of git. Works with Kiro, Cursor, Claude Code, Codex, and any AI agent.

ckpt

Automatic checkpoints for AI coding sessions. Per-step undo, branching, and restore — on top of git.

ckpt watch     # start watching — auto-snapshots every AI change
# ... let Kiro / Cursor / Claude Code / Codex do its thing ...
ckpt steps     # see what happened, step by step
ckpt restore 3 # go back to step 3
ckpt end       # squash into one clean git commit

The problem

AI agents edit your code in rapid bursts — 5, 10, 20 files at once. When something breaks:

• Undo everything (Kiro/Cursor revert) — lose all the good changes too
• Manually figure out which change broke things — painful and slow

No per-step undo. No timeline. No way to try a different approach without losing the first one.

How AI agents handle errors today (and why it's wasteful)

When an AI agent breaks something, here's what actually happens:

1. The agent…

View on GitHub