agent-checkpoint-mcp 0.1.0

Local MCP server that saves work-in-progress checkpoints so any AI agent can resume a multi-step plan exactly where a previous session was cut off.

agent-checkpoint-mcp

Never lose your place when an AI agent session gets cut off.

A tiny, 100% local MCP server that saves work-in-progress checkpoints to SQLite. When a session dies mid-plan — context limit hit, quota exhausted, laptop closed — the next session (same agent or a different one: Claude Code, Codex, Cursor) reads the exact state and continues from the last sub-task instead of redoing work.

• Local-first: SQLite on your machine. No network calls, no API keys, no LLM, zero cost.
• Cross-agent: checkpoints are keyed by project directory, so Claude Code can resume what Codex started.
• Cross-platform: macOS (incl. Apple Silicon), Linux, Windows. Python 3.11+, single dependency (mcp).

The problem

You're 40 minutes into a 6-step plan. The session hits the context limit and compacts — or your quota runs out and you switch agents. The new session sees the plan, maybe, but not that step 3 was half done: the migration file was written but not applied, two of five tests were fixed. So it starts step 3 over. This server makes "exactly where were we?" a tool call.

Install (one command)

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/DiegoWare/agent-checkpoint-mcp/main/install/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/DiegoWare/agent-checkpoint-mcp/main/install/install.ps1 | iex

The installer:

1. Installs the package with uv, pipx, or pip --user (whichever you have).
2. Detects installed agents — Claude Code, Cursor, Codex — and registers the server in each one's MCP config (non-destructively).
3. Prints what it changed. Restart your agent and the agent-checkpoint server is live.

Re-running the installer upgrades and re-registers. Prefer manual control?

pipx install agent-checkpoint-mcp   # or: uv tool install agent-checkpoint-mcp
agent-checkpoint-mcp setup          # add --dry-run to preview config changes

Or register by hand — the server command is just agent-checkpoint-mcp:

// Claude Code (~/.claude.json) and Cursor (~/.cursor/mcp.json)
{ "mcpServers": { "agent-checkpoint": { "command": "agent-checkpoint-mcp", "args": [] } } }

# Codex (~/.codex/config.toml)
[mcp_servers.agent-checkpoint]
command = "agent-checkpoint-mcp"
args = []

Tools

Tool	What it does
save_checkpoint(plan, current_step, total_steps, step_status, what_was_done, what_remains)	Save progress. Designed to be called after every sub-task (a file edited, a test passing), not just when a numbered step completes.
get_checkpoint()	The latest checkpoint for this project, formatted as a resume brief: current step, what's done (don't redo), the exact next action, remaining steps.
list_checkpoints(limit=20)	Session history with timestamps, newest first.
clear_checkpoints(confirm=false)	Wipe this project's history. Dry-run by default; requires confirm=true to delete.

All tools take an optional project_dir override. By default the project is detected from the server's working directory, walking up to the nearest .git root — so checkpoints saved from repo/src/ and repo/ land in the same bucket, and different projects never mix.

Example flow

Session A (Claude Code, dies at context limit):
  save_checkpoint(plan="1. Schema\n2. Endpoints\n3. Tests", current_step=2,
                  total_steps=3, step_status="in_progress",
                  what_was_done="- schema migrated\n- POST /users done",
                  what_remains="- GET /users/:id handler, then wire router")

Session B (Codex, next morning):
  get_checkpoint()
  → # Resume point — step 2/3 (in_progress)
    ## What was already done (do NOT redo this) ...
    ## What remains in the current step — continue HERE ...

Auto-checkpoint setup (recommended)

The server only helps if agents actually call it. Two pieces make that automatic:

1. Instructions file

Copy examples/CLAUDE.md.example into your project's CLAUDE.md (Claude Code) and/or examples/AGENTS.md.example into AGENTS.md (Codex and others). The key rule: save after every concrete sub-task, and call get_checkpoint first when a task looks like a continuation.

2. Claude Code hooks (safety net)

Merge examples/claude-settings-hooks.json into .claude/settings.json (project) or ~/.claude/settings.json (user):

• SessionStart (startup|resume|compact) runs agent-checkpoint-mcp show, which prints the latest checkpoint — Claude Code injects that output into the fresh context. The resuming agent knows where it left off without even calling a tool. This is the main recovery mechanism.
• PreCompact runs agent-checkpoint-mcp precompact-snapshot, which parses the session transcript locally (last todo-list state + last assistant messages) and stores an emergency checkpoint right before compaction. Honest caveat: hooks can't force the model to call an MCP tool, so this snapshot is reconstructed from the transcript — cruder than a proper save_checkpoint, but it means even a session that never saved manually leaves a trail.

Where data lives

One SQLite database, keyed by project path — nothing is written inside your repos:

OS	Path
macOS	~/Library/Application Support/agent-checkpoint-mcp/checkpoints.db
Linux	$XDG_DATA_HOME/agent-checkpoint-mcp/checkpoints.db (default ~/.local/share/...)
Windows	%LOCALAPPDATA%\agent-checkpoint-mcp\checkpoints.db

Override with the AGENT_CHECKPOINT_HOME environment variable.

CLI

agent-checkpoint-mcp                      # run the MCP server (stdio) — what agent configs execute
agent-checkpoint-mcp show [--project D]   # print the latest checkpoint (used by the SessionStart hook)
agent-checkpoint-mcp list [--project D]   # checkpoint history
agent-checkpoint-mcp clear [--yes]        # delete this project's checkpoints
agent-checkpoint-mcp setup [--dry-run]    # (re)register with detected agents
agent-checkpoint-mcp precompact-snapshot  # used by the PreCompact hook (hook JSON on stdin)

Development

git clone https://github.com/DiegoWare/agent-checkpoint-mcp
cd agent-checkpoint-mcp
python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
.venv/bin/pytest

License

MIT