Skip to main content
Glama
DiegoWare

agent-checkpoint-mcp

by DiegoWare
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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: local-agent-context

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

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

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:

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

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

Available Tools

4 tools
clear_checkpointsA

Delete all checkpoints for this project. Requires confirm=true.

Called without confirm, it only reports how many checkpoints would be deleted; ask the user before calling again with confirm=true.

Args: confirm: Must be true to actually delete. False = dry run. project_dir: Optional project directory override; defaults to the server's working directory (walking up to the nearest .git root).

ParametersJSON Schema
NameRequiredDescriptionDefault
confirmNo
project_dirNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

In the absence of annotations, the description discloses the dry-run behavior and the requirement for confirmation. However, it does not mention edge cases like zero checkpoints or result format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise and well-structured with a clear main sentence and bullet-pointed Args. Slightly verbose in the dry-run explanation, but overall efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given sibling tools and the presence of an output schema, the description covers the essential functionality and parameter behavior. Could add a word about response format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully explains both parameters: confirm's dry run vs delete behavior, and project_dir's default resolution policy.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Delete all checkpoints for this project', using a specific verb and resource. It distinguishes itself from siblings like get_checkpoint, list_checkpoints, and save_checkpoint.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly explains when to use confirm=false (dry run) vs confirm=true (actual deletion), and instructs to ask user before deleting. Provides clear usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_checkpointA

Get the latest checkpoint for this project — where to resume from.

Call this FIRST when a task looks like a continuation of earlier work (e.g. after a session was cut off). It returns the plan, the current step, what was already done (do not redo it), and the exact next action.

Args: project_dir: Optional project directory override; defaults to the server's working directory (walking up to the nearest .git root).

ParametersJSON Schema
NameRequiredDescriptionDefault
project_dirNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses what is returned (plan, current step, done actions, next action) and implies a read operation via 'Get', but does not explicitly state any behavioral traits like idempotency, side effects, or safety. Adequate but could be more explicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two sentences in the first paragraph plus a brief bullet-like explanation of return values. Every sentence adds value with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists, the description appropriately explains the tool's purpose and return content (plan, step, done actions, next action). It could mention what happens if no checkpoint exists, but overall is sufficient for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage, but the description explains the optional project_dir parameter: 'Optional project directory override; defaults to the server's working directory (walking up to the nearest .git root).' This adds clear meaning beyond the schema's bare 'Project Dir' label.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Get the latest checkpoint for this project — where to resume from.' This is a specific verb ('Get') and resource ('checkpoint'), and distinguishes from siblings (clear_checkpoints, list_checkpoints, save_checkpoint) by focusing on resumption.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Call this FIRST when a task looks like a continuation of earlier work (e.g. after a session was cut off).' This provides clear context for use, though it does not explicitly mention when not to use or compare directly with siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_checkpointsA

List the checkpoint history for this project, newest first, with timestamps.

Args: limit: Maximum number of checkpoints to return (default 20). project_dir: Optional project directory override; defaults to the server's working directory (walking up to the nearest .git root).

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
project_dirNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses key behaviors: returns history with timestamps, ordered newest first, default limit, and project_dir resolution. No annotations exist, so description carries full burden; it covers main behavior without need for additional detail like auth or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two distinct sections: one-line purpose followed by Args list. Every sentence adds value, no redundancy, front-loaded with key information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists (assumed) and parameters are fully described, no gaps remain. Siblings are accounted for by distinctive purpose. Simple list tool fully covered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, description adds essential meaning: limit default and max count, project_dir default and resolution strategy. This goes beyond type info in schema, making parameters clear.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the verb 'list' and resource 'checkpoint history' with ordering (newest first) and content (timestamps). Differentiates from siblings like get_checkpoint and save_checkpoint by being a list operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context: lists checkpoints for a project. Does not explicitly state when not to use or mention alternatives, but the purpose is straightforward and distinguishable from siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

save_checkpointA

Save a progress checkpoint so any future agent session can resume exactly here.

Call this after EVERY concrete sub-task (a file edited, a test passing, a command run) — not only when a numbered step finishes. Frequent, small checkpoints are the point: if the session dies mid-step, the next agent resumes from the last sub-task instead of redoing the whole step.

Args: plan: The full numbered plan being executed (all steps, verbatim). current_step: 1-based number of the step currently being worked on. total_steps: Total number of steps in the plan. step_status: "in_progress", "done", or "blocked" — status of current_step. what_was_done: Everything completed so far, across all steps, specific enough that another agent will not redo any of it. what_remains: What is still missing IN THE CURRENT STEP, specific enough to be the very next action (plus any known remaining steps). project_dir: Optional project directory override; defaults to the server's working directory (walking up to the nearest .git root).

ParametersJSON Schema
NameRequiredDescriptionDefault
planYes
project_dirNo
step_statusYes
total_stepsYes
current_stepYes
what_remainsYes
what_was_doneYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses the purpose and parameter roles, but does not specify whether it overwrites existing checkpoints or enforces any constraints like uniqueness per step.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured: a concise purpose sentence, followed by usage guidance, then a clearly labeled Args section. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (7 parameters, no annotations, no schema descriptions), the description provides complete guidance on purpose, usage, and parameter semantics. The presence of an output schema covers return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has zero descriptions for parameters (0% coverage). The description compensates fully with a detailed Args section explaining the meaning and expected content of each parameter, including optional project_dir.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Save a progress checkpoint so any future agent session can resume exactly here.' It distinguishes itself from sibling tools (clear, get, list) by focusing on creation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance on when to call: 'Call this after EVERY concrete sub-task...Frequent, small checkpoints are the point.' It implies not to call only at step boundaries, but does not explicitly address when not to use this tool versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 4 tool updatesv0.1.1
    • First observedclear_checkpoints
    • First observedget_checkpoint
    • First observedlist_checkpoints
    • First observedsave_checkpoint
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0
Disambiguation5/5

Each tool serves a distinct purpose: clear deletes all checkpoints, get retrieves the latest, list shows history, save creates a new checkpoint. There is no overlap in functionality.

Naming Consistency4/5

All tools follow a verb_noun pattern in snake_case. However, 'clear_checkpoints' uses plural 'checkpoints' while the others use singular 'checkpoint', which is a minor inconsistency.

Tool Count5/5

With only 4 tools, the server is tightly scoped for checkpoint management. Each tool covers a necessary operation (save, retrieve, list, clear) without unnecessary bloat.

Completeness4/5

The set covers the core workflow: saving checkpoints, retrieving the latest, listing history, and clearing all. A minor gap is the inability to retrieve an arbitrary checkpoint by ID, but the design focuses on the latest checkpoint for session resumption.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/DiegoWare/agent-checkpoint-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server