TokenPatch

Let AI edit your codebase safely. You decide which files it can touch. Auto-backup before every change. One command to roll back anything.

tokenpatch.com · Quickstart · Install

tokenpatch puts a safety layer between your AI coding assistant and your code. You tell it which files are fair game. It snapshots your project, lets the AI work, checks that it stayed within bounds, and gives you a clean diff to review. If something goes wrong — one command to undo.

Works with Codex, Claude Code, Cursor, WorkBuddy, or any MCP-capable agent.

---

The problem

AI coding assistants are powerful but unpredictable. They can modify files you didn't intend, introduce breaking changes, or take your project in a wrong direction. And when they do, there's no easy undo.

Developers don't need another AI tool. They need to trust the ones they already use.

---

How tokenpatch helps

1. You set the boundary

tp: fix the login redirect bug. Only modify src/auth/login.tsx.

tokenpatch enforces this. If the AI tries to touch anything outside src/auth/login.tsx, the patch is rejected.

2. Auto-checkpoint, always

Before every AI edit, tokenpatch snapshots your project using git. No setup required. If the AI takes the wrong approach, you're one command away from where you started:

tokenpatch checkpoint restore <id> --yes

3. Review before you commit

tokenpatch diff

See exactly what changed, file by file. Accept the patch, roll back, or refine — your call.

4. Everything is tracked locally

All AI edits, checkpoints, and costs are recorded in .mmdev/ inside your project. No data leaves your machine. Team audits become trivial.

---

Quick Start

pip install git+https://github.com/Leoyen1/tokenpatch.git
tokenpatch bootstrap

Configure executor credentials once:

MMDEV_EXECUTOR_PROVIDER=deepseek_byok
DEEPSEEK_API_KEY=your-deepseek-key
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_EXECUTOR_MODEL=deepseek-v4-pro

Then use it inside your coding app:

tp: add pagination to the user list. Only modify src/users.tsx and src/users.css.

Check what happened:

tokenpatch diff                    # see what changed
tokenpatch metrics                 # see what it cost
tokenpatch checkpoint list         # see restore points

---

Key Features

Feature	What it does
File boundaries	AI edits are rejected if they touch files outside allowed_files. You control the blast radius.
Auto-checkpoints	Every AI edit creates a git-backed restore point. No setup, no thinking — it just happens.
Visual diff	See every changed line before accepting. tokenpatch diff or tokenpatch diff --web for browser preview.
One-click rollback	tokenpatch checkpoint restore <id> --yes. That's it.
Local audit trail	All edits, costs, and checkpoint history live in .mmdev/. Nothing phones home.
MCP native	14 MCP tools for AI assistants to call directly — no shell commands needed.
Cost tracking	Know exactly what each AI edit costs. Not a savings promise — just honest accounting.

---

Common Commands

tokenpatch bootstrap                                    # one-time setup
tokenpatch do "fix a bug" --allowed-file src/utils.py   # quick single-file edit
tokenpatch auto --isolation worktree "add search"       # full safe pipeline
tokenpatch diff                                         # review what changed
tokenpatch checkpoint list                              # see restore points
tokenpatch checkpoint restore <id> --yes                # undo
tokenpatch metrics                                      # cost and usage

---

Safety by default

tokenpatch doesn't guess what's safe. It enforces explicit boundaries:

• No file outside allowed_files gets modified. Period.
• Checkpoints are git-backed — they survive tool restarts and machine reboots.
• All records stay in your project. No cloud dependency, no data leakage.
• The --isolation worktree mode creates a separate git worktree so your working directory stays untouched until you explicitly approve.

Configure project-level safety rules in .tokenpatch/safety.toml:

[boundaries]
always_protect = ["package.json", "*.lock", "migrations/", "config/"]
warn_on_delete = true
max_files_per_run = 5
require_human_approval = ["src/auth/", "src/billing/"]

Sensitive paths remain blocked unless the user explicitly approves that one run:

tokenpatch do "update the login validation" \
  --allowed-file src/auth/login.py \
  --approve-sensitive

--approve-sensitive never overrides always_protect. In CI, compare the complete change set against the intended base revision:

tokenpatch ci-check --base origin/main --allow "src/**"

---

Works With

• Codex App and Codex CLI
• Claude Code
• Cursor
• WorkBuddy
• VS Code / Cline / any MCP-capable agent
• Terminal workflows and CI

---

What tokenpatch is not

• Not a replacement for your AI coding assistant. It works alongside the one you already use.
• Not a model proxy or observability platform. It's a safety layer for code changes.
• Not a guarantee that AI-generated code is correct. It guarantees the AI stays within the files you allowed.
• Not a cloud service by default. Everything runs locally. Cloud features (team audit, policy sync) are optional add-ons.

---

TokenPatch and Aider

Aider is an interactive terminal pair programmer. TokenPatch is a safety layer that sits between your existing coding assistant and your code. Use Aider for an evolving coding conversation; use TokenPatch when you want bounded, checkpointed, auditable AI edits with the assistant you already use. The tools can also work together.

See the comparison: TokenPatch vs Aider.

---

Docs

• Quickstart
• Install Guide
• FAQ
• MCP Client Setup
• Integration Guide
• Public Release Manifest

---

Development

git clone https://github.com/Leoyen1/tokenpatch
cd tokenpatch
python -m pip install -e ".[test,web]"
python -m pytest -q

CI runs unit tests and example tests through GitHub Actions.