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.

Related MCP server: mcp-taskflow

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

That single command does everything:

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. Installs the Claude Code recovery hooks (see below): every new, resumed, or compacted session automatically receives the latest checkpoint, and an emergency checkpoint is saved right before every compaction.

4. Prints what it changed. Restart your agent and everything is live.

Re-running the installer upgrades and re-registers.

Don't want a piece of it? Everything is reversible with one command:

agent-checkpoint-mcp uninstall --hooks   # remove the Claude Code hooks only
agent-checkpoint-mcp uninstall --mcp     # remove the MCP registrations only
agent-checkpoint-mcp uninstall           # remove both

(Or skip hooks at install time: AGENT_CHECKPOINT_NO_HOOKS=1 curl ... | bash, and agent-checkpoint-mcp setup --no-hooks thereafter. --dry-run previews any of these without writing.)

Prefer manual control end to end?

pipx install agent-checkpoint-mcp   # or: uv tool install agent-checkpoint-mcp
agent-checkpoint-mcp setup          # same as the installer's registration step

Docker-isolated install (Agent Checkpoint + Codebase Memory)

If you do not want either MCP installed into the host Python environment, this repository includes an optional Docker path for macOS and Linux. From a clone of this repository, run:

./install/docker.sh install

That one command builds a local agent-checkpoint-mcp:local image containing this project and the checksum-verified codebase-memory-mcp v0.8.1 binary, then registers both servers with detected Claude Code, Cursor, and Codex installations. The clients launch one short-lived stdio container per MCP connection; there are no background services or open ports.

At runtime each container has no network, runs as a non-root user with dropped capabilities, and sees only the active Git repository at its original absolute path. The repository mount and container root are read-only. Checkpoints and code indexes persist in separate Docker volumes, so Codebase Memory cannot create .codebase-memory/graph.db.zst or otherwise edit source files.

Manage either MCP independently:

./install/docker.sh disable codebase       # keep Agent Checkpoint
./install/docker.sh enable codebase
./install/docker.sh disable checkpoint     # also removes its Claude hooks
./install/docker.sh enable checkpoint
./install/docker.sh doctor                 # config + stdio handshake checks
./install/docker.sh uninstall              # keep image and persistent data

Disabling or uninstalling never deletes data. Purging is separate and requires an explicit confirmation flag:

./install/docker.sh purge checkpoint --yes
./install/docker.sh purge codebase --yes
./install/docker.sh purge all --yes

The registrations point to the launcher inside this checkout, so keep the clone at the same path. Docker limits accidental host exposure, but anyone who controls the Docker daemon or the host root account can still access Docker volumes and mounts.

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

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 ...

How recovery works

Two mechanisms, both installed automatically by the one-command installer:

Claude Code hooks (installed for you)

The installer merges two hooks into ~/.claude/settings.json (non-destructively — your existing hooks are untouched):

• 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.

Remove them anytime with agent-checkpoint-mcp uninstall --hooks. To merge them by hand instead (e.g. per-project in .claude/settings.json), use examples/claude-settings-hooks.json.

Per-project instructions (one command per project)

For the best checkpoints — saved deliberately after every sub-task, not just recovered from transcripts — run this once inside a project:

agent-checkpoint-mcp init

It appends a checkpoint-discipline section to the project's CLAUDE.md and AGENTS.md (creating them if needed, skipping if already present). The key rule it teaches: save after every concrete sub-task, and call get_checkpoint first when a task looks like a continuation. Prefer to copy by hand? See examples/.

Where data lives

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

The Docker variant stores checkpoints in the agent-checkpoint-mcp-checkpoints volume and Codebase Memory indexes in the agent-checkpoint-mcp-codebase volume.

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 init [--project D]   # add checkpoint instructions to CLAUDE.md/AGENTS.md
agent-checkpoint-mcp setup [--no-hooks]   # (re)register with detected agents + install hooks
agent-checkpoint-mcp uninstall [--hooks|--mcp]  # remove what setup installed
agent-checkpoint-mcp precompact-snapshot  # used by the PreCompact hook (hook JSON on stdin)

setup and uninstall accept --dry-run to preview changes without writing.

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