Metadata-Version: 2.4
Name: agent-checkpoint-mcp
Version: 0.1.0
Summary: 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.
Project-URL: Homepage, https://github.com/DiegoWare/agent-checkpoint-mcp
Project-URL: Repository, https://github.com/DiegoWare/agent-checkpoint-mcp
Project-URL: Issues, https://github.com/DiegoWare/agent-checkpoint-mcp/issues
Author: Diego Gonzalez
License-Expression: MIT
License-File: LICENSE
Keywords: agent,checkpoint,claude-code,codex,cursor,mcp,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: mcp>=1.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# agent-checkpoint-mcp

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

A tiny, 100% local [MCP](https://modelcontextprotocol.io) 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**

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

**Windows (PowerShell)**

```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?

```bash
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`:

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

```toml
# 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

```text
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`](examples/CLAUDE.md.example) into your
project's `CLAUDE.md` (Claude Code) and/or
[`examples/AGENTS.md.example`](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`](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

```text
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

```bash
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](LICENSE)
