Clumsy

Local checkpoint and restore MCP server for AI coding agents.

Clumsy creates a lightweight timeline of your code changes, stores raw file content locally, and restores only after you review and confirm the restore plan.

Install

npm install -g clumsy-mcp

Verify:

clumsy --help

Clumsy CLI output is human-first: short, colored, and minimal. Normal commands do not dump raw JSON.

Setup for your AI agent

Initialize the current project:

clumsy init

This creates .clumsy/, adds the Clumsy block to AGENTS.md, and creates the first checkpoint.

Run this inside your project:

clumsy install

Select your AI agent with the arrow-key menu, then press Enter.

Supported targets include Codex, Claude Code, Cursor, Gemini CLI, GitHub Copilot, Windsurf, Cline, Roo Code, OpenCode, Amazon Q, and Continue.

After setup, restart your AI agent so it can load the MCP server.

When the MCP server runs, initialized projects are auto-watched and file changes are checkpointed after a short debounce.

Codex quick setup

clumsy install --target codex --yes

This updates:

• AGENTS.md in the current project
• ~/.codex/AGENTS.md
• ~/.codex/config.toml

Then restart Codex.

Manual MCP config

If you prefer to configure the MCP server yourself:

{
  "mcpServers": {
    "clumsy": {
      "command": "clumsy",
      "args": ["serve"]
    }
  }
}

CLI

Initialize the current project:

clumsy init

Install for your AI agent:

clumsy install

Create a checkpoint:

clumsy checkpoint --label "before refactor"

Show project status:

clumsy status

Run the watcher manually:

clumsy watch

List checkpoints:

clumsy list

Search checkpoints:

clumsy list --query refactor

Preview a restore:

clumsy plan --query "before refactor"

Restore after confirmation:

clumsy restore --id <checkpoint-id> --confirm "RESTORE <checkpoint-id>"

MCP tools

• checkpoint_create
• checkpoint_list
• restore_plan
• restore_confirmed
• agents_instructions
• checkpoint_defaults
• watcher_status

Storage

Clumsy stores data locally in:

.clumsy/

It stores raw file content as deduplicated SHA-256 blobs and keeps a manifest for every checkpoint.

By default, Clumsy stores text/code files only. Binary files, images, archives, documents, and files over 5 MB are skipped unless explicitly included.

By default, Clumsy skips common unwanted files and folders such as:

• node_modules/
• dist/
• build/
• .env
• dot-folders like .git/, .vscode/, .github/, .cursor/, .clumsy/

Use --include if you need to capture an ignored file:

clumsy checkpoint --include ".vscode/settings.json"

Use --include to capture a binary file intentionally:

clumsy checkpoint --include "assets/logo.png"

Safety

Clumsy never restores automatically.

Restore always works like this:

1. Create a restore plan
2. Verify required blobs exist and match their SHA-256 hashes
3. Review the file changes
4. Confirm with the exact token
5. Restore