Checkpoint

A checkpoint is a saved snapshot of your file state that lets you roll back an AI coding agent's changes to a known-good point. Most modern agentic coding CLIs — including Claude Code, Codex CLI, and their alternatives — create checkpoints automatically so you can experiment with agent edits without worrying about losing work.

Why it matters

Agents sometimes go off-track: they "fix" the wrong file, introduce a bug during a refactor, or make edits you decide you don't want. Without checkpoints, you'd rely on git — which only tracks committed state — and Ctrl+Z in your editor (which doesn't span files). Checkpoints give you a safety net that works across the whole project and fits the iterative nature of vibe coding.

In SpaceSpider, checkpoints are per-CLI (managed by whatever tool is running in each pane), not a global SpaceSpider feature. Claude Code, Codex CLI, and the others handle their own snapshots.

How it works

Implementations vary but the general pattern is:

1. Before each meaningful change (or each turn), the CLI captures the current state of files it plans to touch
2. Apply the edit
3. Keep a stack of checkpoints for the current session
4. Expose a command (/rewind, /undo, /checkpoint list) to jump back

Claude Code's checkpoint system is tied into its transcript — each turn becomes a checkpoint you can rewind to. The file changes made since that turn are reverted when you rewind.

Checkpoints usually live in a hidden directory (.claude/checkpoints/ or similar) and are pruned after the session ends or by age.

How it's used

Typical checkpoint usage:

• "That refactor made things worse, rewind to before it"
• "I want to try two approaches — keep a checkpoint at the fork"
• "The agent deleted a test I wanted to keep, restore just that file"

For bigger safety, pair checkpoints with:

• Git worktrees so different experiments don't collide
• Plan mode to avoid needing to rewind in the first place
• Sandbox modes that prevent destructive shell commands

Related terms

• Plan mode — prevention; checkpoints are recovery
• Sandbox — contains blast radius
• Git worktree — parallel isolated workspaces
• Hook — can trigger custom checkpoint events
• Claude Code — canonical checkpoint implementation

FAQ

Are checkpoints a replacement for git commits?

No. Checkpoints are session-scoped and CLI-specific; commits are durable and shared across tools. Commit when you're happy with a chunk of work; use checkpoints inside a session to iterate.

Do checkpoints capture non-file state?

Mostly no — checkpoints snapshot files, not database state, external service state, or environment variables. For anything outside the repo, you need your own backup strategy.