complete-checkpoint

Your code should never be one bad AI edit away from disaster.

AI coding agents rewrite dozens of files in seconds. One wrong instruction and your working project is broken. complete-checkpoint gives you save points: snapshot your workspace before risky operations, and roll back to a known-good state when things go wrong.

It captures workspace files and agent metadata (like Claude project data) separately, so you can restore one without touching the other.

Features

• Atomic Save & Restore - Snapshot your workspace and restore it in one command. No partial states, no corruption.
• Workspace + Agent Data - Captures your files and agent metadata independently. Restore one, both, or neither.
• Auto-Checkpointing - Hook into Claude Code to save before tool calls, compaction, or session start.
• Prefix ID Matching - Type just the first few characters of a checkpoint ID to restore or delete it.
• Dry-Run Preview - See exactly what a restore would change before committing.
• Retention Policies - Auto-saves cap at 50 per workspace. Storage stays under control.
• Interactive Mode - Browse and pick checkpoints interactively when you skip the ID.
• Error Logging - Auto-save failures log to ~/.complete-checkpoint/error.log.

Quick Start

Install

Requires Rust 1.70+.

cargo install complete-checkpoint

Save, restore, done

No setup required. Just start using it:

complete-checkpoint save -m "Before refactoring auth module"
# ... AI makes changes ...
complete-checkpoint restore   # Roll back to the save point

Usage

Save a checkpoint

$ complete-checkpoint save -m "Before refactoring auth module"
Checkpoint saved: 019d53ea
  Message: Before refactoring auth module

List checkpoints

$ complete-checkpoint list
019d53ea  25 seconds ago    manual                Initial commit
a4f2c801  2 hours ago       PreToolUse(Bash)      Fixed parser        [auto]
7bc91d3f  3 hours ago       PreCompact            Before compaction   [auto]

Filter by type or trigger:

complete-checkpoint list -n 5
complete-checkpoint list --auto        # Only auto-saved checkpoints
complete-checkpoint list --manual      # Only manual checkpoints
complete-checkpoint list --trigger PreToolUse

In a terminal, list without filters opens interactive selection:

? Select a checkpoint:
> 019d53ea  25 seconds ago    manual                Initial commit
  a4f2c801  2 hours ago       PreToolUse(Bash)      Fixed parser        [auto]
  7bc91d3f  3 hours ago       PreCompact            Before compaction   [auto]

Show checkpoint details

$ complete-checkpoint show 019d53ea
Checkpoint:  019d53ea (019d53ea-ff34-7d03-b5b6-a98d0c22d59c)
Created:     2026-04-03 15:16:42 UTC (25 seconds ago)
Trigger:     manual
Session:     (none)
Message:     Initial commit
Type:        manual
Agent:       claude
Workspace:   /Users/you/my-project

Restore to a checkpoint

Without an ID, interactive mode lets you pick and preview before restoring:

? Select a checkpoint:
> 019d53ea  25 seconds ago    manual    Initial commit
  a4f2c801  2 hours ago       PreToolUse(Bash)      Fixed parser        [auto]

Workspace:  +0 ~1 -0 (=12 unchanged)
Agent data: +0 ~0 -0 (=2 unchanged)

? Restore to this checkpoint? (y/n)

Or use directly:

complete-checkpoint restore abc123       # Prefix match supported
complete-checkpoint restore --dry-run    # Preview changes first
complete-checkpoint restore --only workspace  # Workspace files only
complete-checkpoint restore --only agent      # Agent data only

Delete a checkpoint

Without an ID, interactive mode asks for confirmation:

? Select a checkpoint:
> 019d53ea  25 seconds ago    manual    Initial commit

? Delete checkpoint 019d53ea (Initial commit)? (y/n)
Deleted checkpoint 019d53ea

Or delete directly:

complete-checkpoint delete abc123    # Delete by ID

Auto-checkpointing with Claude Code

Install hooks to auto-save before tool calls, compaction, and session starts:

$ complete-checkpoint hook install
Hook installed in ~/.claude/settings.json

Remove hooks:

$ complete-checkpoint hook uninstall
Hook removed from ~/.claude/settings.json

Configuration

All settings have sensible defaults and work without any setup. Customize per-project or globally via CLI:

$ complete-checkpoint config list
agent = "claude" [default]
triggers.on_session_start = true [default]
triggers.on_tool_call = true [default]
triggers.on_turn = false [default]
workspace.include_deps = false [default]

complete-checkpoint config set triggers.on_turn true          # Project-level
complete-checkpoint config set --global triggers.on_turn true # Global default
complete-checkpoint config get triggers.on_turn               # Check a value

Configuration is stored under ~/.complete-checkpoint/ (not in your project directory). Priority: hardcoded defaults < global config < project config.

You can also run complete-checkpoint init to create a project config with defaults:

complete-checkpoint init                  # Uses default agent (claude)
complete-checkpoint init --agent claude   # Explicit agent type

Status and logs

$ complete-checkpoint status
Project:         /Users/you/my-project
Agent:           claude [default]
Triggers:
  on_session_start: true [default]
  on_tool_call:     true [default]
  on_turn:          false [default]
Include deps:    false [default]
Last checkpoint: 019d53ea (2026-04-03 15:16:42)

complete-checkpoint logs            # Recent auto-save errors
complete-checkpoint logs -n 50      # Show more lines
complete-checkpoint logs --clear    # Clear the log file

Contributing

Contributions are welcome. Please read the Contributing Guide before submitting a pull request.

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Author

Yein Sung - GitHub