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:

• The agent notices the error (or you tell it)

• It re-reads the files it already wrote to understand the current state

• It reasons about what went wrong — burning tokens on analysis

• It rewrites the files — often re-generating code it already had right

• If the fix doesn't work, repeat steps 2-4 again. And again.

Every cycle costs tokens, time, and context window. A simple revert that should take milliseconds instead takes 30-60 seconds and hundreds of tokens as the agent manually reconstructs what it already had.

With ckpt: ckpt restore 3 — instant rollback to the last good state. Zero tokens. Zero re-reading. Zero re-writing.

"But my IDE already has checkpoints"

Yes. Cursor has timeline. Kiro has revert. Windsurf has checkpoints. Here's what ckpt does differently:

1. The AI agent can operate it — not just you

IDE checkpoints are buttons in a UI. The human clicks "revert." The AI agent can't.

With ckpt, the agent itself runs ckpt restore 3. It becomes self-correcting — it can checkpoint its own work, detect when something broke, roll back, and try a different approach. No human in the loop. No IDE UI needed.

This is the core difference. IDE checkpoints are a human safety net. ckpt is an AI capability.

2. Terminal agents have nothing

Claude Code, Codex, Aider, and any agent running in a terminal have zero checkpoint support. No UI, no revert button, nothing. When they break something, they brute-force fix it by re-reading and rewriting — slow, expensive, and often makes things worse.

ckpt is the only checkpoint system that works for terminal-based agents.

3. Branching — try multiple approaches

No IDE has this. ckpt try approach-a -r 2 saves the current work, goes back to step 2, and lets the agent try a completely different approach. Then ckpt trydiff approach-a compares the two. The agent (or you) picks the better one.

IDEs give you undo. ckpt gives you branching exploration.

4. Persistent history

IDE checkpoints disappear when you close the session or the IDE. ckpt log keeps every session permanently. Weeks later you can see exactly what the agent did, step by step.

5. Works everywhere

IDE checkpoints only work inside that IDE. ckpt works in any terminal, any CI pipeline, any environment. It's just git.

Feature IDE checkpoints ckpt

AI agent can use it ✗ ✓

Terminal agents (Codex, Aider, Claude Code) ✗ ✓

Branch & compare approaches ✗ ✓

Persistent history ✗ ✓

Works outside IDE ✗ ✓

Step tagging ✗ ✓

Auto-snapshot ✓ ✓

Per-step restore ✓ ✓

What happens when AI agents use ckpt

ckpt is a CLI. Every AI coding agent can already run shell commands. No plugins, no integrations, no MCP servers. Just tell the agent to use it.

Add this to your prompt or system instructions:

Run ckpt watch in the background before starting work. It auto-snapshots every change you make. If something breaks, run ckpt restore instead of manually rewriting. To try a different approach, run ckpt try -r . When done, run ckpt end.

For richer snapshots with reasoning, use ckpt snap "why you made this change" after each logical step instead of relying on auto-snapshots.

Here's what changes:

Faster error recovery

Without ckpt: agent breaks something → re-reads files → reasons about the error → rewrites the fix → maybe breaks it again → repeat. 30-60 seconds per cycle.

With ckpt: ckpt restore 3 → back to the last good state in milliseconds. Try a different approach immediately.

Cheaper sessions

Every time an agent re-reads and rewrites files to fix a mistake, that's tokens you're paying for. A typical error-fix cycle costs 500-2000 tokens just to get back to where you were. ckpt eliminates that entire cost — restore is free.

Better results through exploration

Without ckpt, agents commit to one approach and push forward. If it doesn't work, they patch on top of patches until the code is a mess.

With ckpt, an agent can:

• Try approach A → ckpt snap "approach A: class-based"

• Hit a wall → ckpt try approach-a -r 1 (save A, go back)

• Try approach B → ckpt snap "approach B: hooks-based"

• Compare → ckpt trydiff approach-a

• Pick the better one

This is how good developers work. ckpt gives AI agents the same workflow.

Cleaner context windows

When an agent manually reverts by rewriting, it fills the context window with "oops, let me fix that" back-and-forth. With ckpt, a failed approach is ckpt restore 3 — one line instead of 20 messages of debugging. The context stays clean for actual work.

Beyond coding — any AI that produces files at scale

ckpt isn't just for coding agents. Any AI system that generates, edits, or manages files can use it — content pipelines, design tools, data processing, infrastructure-as-code generators, documentation bots.

The pattern is the same everywhere: AI generates output at scale → something goes wrong halfway through → you either lose everything or manually figure out where it broke.

The bigger the output, the worse the problem. An AI that edits 50 files in a batch has 50 chances to break something. Without checkpoints, one bad edit means re-running the entire batch. With ckpt, you restore to the last good state and only redo what failed.

This is infrastructure. Any company running AI agents in production — whether they're writing code, generating reports, or managing configs — needs a way to checkpoint, inspect, and roll back AI work. ckpt is that layer.

Works with any AI agent

Agent Works? How

Kiro ✓ Runs shell commands natively

Cursor ✓ Runs shell commands natively

Claude Code ✓ Runs shell commands natively

OpenAI Codex ✓ Runs shell commands natively

GitHub Copilot ✓ Via terminal

Windsurf ✓ Runs shell commands natively

Aider ✓ Runs shell commands natively

Any human ✓ It's a CLI

What ckpt does

ckpt watches your project while an AI agent works. Every time the agent pauses, ckpt takes a snapshot. You get a timeline of every step, and you can restore to any point.

It's just git under the hood — hidden branch, real commits, squash when done.

Install

npm install -g @mohshomis/ckpt

Usage

Auto mode (recommended)

ckpt watch

That's it. Let your AI agent work. ckpt snapshots automatically.

Manual mode

Restore

Tag steps

Try multiple approaches

AI tries approach B from step 2

ckpt snap "approach B: used hooks instead of HOCs"

Compare the two approaches

ckpt trydiff approach-a

List all experiments

ckpt tries`

Range diff

Session history

End a session

All commands

Command What it does

ckpt watch Auto-snapshot file changes

ckpt start Start a session manually

ckpt snap Manual snapshot with a reason

ckpt steps List all snapshots

ckpt diff [step] Diff for one step or between two

ckpt why Show why a step was made

ckpt tag Tag a step (good, broken, etc.)

ckpt restore [step] Go back to a step

ckpt restore --last-good Go back to last "good" step

ckpt try [-r step] Branch to try a different approach

ckpt trydiff Compare with an experiment branch

ckpt tries List experiment branches

ckpt end Squash into one commit

ckpt log Show all past sessions

ckpt status Current session info

How it works

• ckpt start creates a hidden branch: ckpt/session/

• Each snapshot = a real git commit on that branch

• ckpt restore = git reset --hard to that commit

• ckpt try = git branch at current HEAD

• ckpt end = git merge --squash back to your branch

• Session history saved to .ckpt/history/

No database. No new format. Just git.

Smart auto-labels

In watch mode, ckpt auto-categorizes changes:

License

MIT