Metadata-Version: 2.4
Name: agent-checkpoint-mcp
Version: 0.1.1
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
```

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:

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

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

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

## 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`](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:

```bash
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/`](examples/).

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

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