Metadata-Version: 2.4
Name: tokenpatch
Version: 0.1.1
Summary: Bounded, auditable AI code patch execution for existing coding agents.
Project-URL: Homepage, https://tokenpatch.com
Project-URL: Documentation, https://tokenpatch.com/docs/tokenpatch
Project-URL: Repository, https://github.com/Leoyen1/tokenpatch
Project-URL: Product definition, https://tokenpatch.com/what-is-tokenpatch
Project-URL: TokenPatch vs Aider, https://tokenpatch.com/compare/tokenpatch-vs-aider
Project-URL: Issues, https://github.com/Leoyen1/tokenpatch/issues
Keywords: ai-coding,coding-agent,code-patch,token-optimization,codex,claude-code,cursor,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2
Requires-Dist: typer>=0.12
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Provides-Extra: web
Requires-Dist: fastapi>=0.115; extra == "web"
Requires-Dist: jinja2>=3.1; extra == "web"
Requires-Dist: uvicorn>=0.30; extra == "web"
Dynamic: license-file

# TokenPatch

Bounded, auditable AI code patch execution for existing coding agents.

[tokenpatch.com](https://tokenpatch.com) · [Quickstart](docs/QUICKSTART.md) · [Install](docs/INSTALL.md) · [Demo evidence](docs/DEMO.md)

tokenpatch lets Codex, Cursor, Claude Code, CLI agents, and MCP clients keep their configured strong model in charge, then route bounded implementation patches to a cheaper executor such as DeepSeek V4 Pro.

The metric is not just request cost. tokenpatch focuses on **cost per applied AI coding patch**.

## What is TokenPatch?

TokenPatch is an open-source execution layer for small, well-defined AI coding changes. It does not replace your primary coding agent. The primary agent plans and reviews; TokenPatch executes an eligible patch with explicit file boundaries, a recovery checkpoint, patch validation, and task-level cost records.

TokenPatch is best suited to narrow, testable work where allowed files and acceptance criteria can be stated before execution. It is not a generic model proxy, a full observability platform, or a substitute for engineering review.

Canonical product definition: [tokenpatch.com/what-is-tokenpatch](https://tokenpatch.com/what-is-tokenpatch).

![tokenpatch report snapshot](docs/assets/report-snapshot.png)

## Quick Start

The first public release is BYOK-first. Bring your own DeepSeek API key.

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

Set executor credentials in your app's MCP environment settings, shell, or `~/.tokenpatch/config.toml`:

```text
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 ask inside Codex, Claude Code, Cursor, or another coding agent:

```text
tp: change the page title. Only modify index.html.
```

Check the result:

```bash
tokenpatch metrics
tokenpatch report
```

## What You Get

- Keep using Codex, Claude Code, Cursor, or your own agent.
- Route bounded implementation work to a lower-cost executor.
- Check `allowed_files` before applying patches.
- Create local recovery checkpoints before AI edits.
- Report actual executor cost, all-strong baseline estimate, savings ratio, and cost per applied patch.
- Keep GPT/Claude keys in your existing coding app; tokenpatch only needs executor credentials for App Mode.

## Example Report Signal

```text
Task: change page title, only modify index.html
All-strong estimate: $0.42
tokenpatch actual: $0.08
Saved: 81%
Patch applied: yes
Tests: passed
```

The numbers above are an illustrative demo snapshot, not a universal guarantee. Real savings depend on task size, retries, model pricing, cache behavior, and review strategy.

## How It Works

```text
Strong model plans and reviews
        |
        v
tokenpatch creates a bounded executor task
        |
        v
DeepSeek V4 Pro writes the patch
        |
        v
tokenpatch checks allowed_files, applies the patch, and reports cost
```

## Works With

- Codex App and Codex CLI
- Claude Code
- Cursor
- VS Code / Cline / other MCP-capable agents
- Terminal workflows and CI

You can ask in any language. The docs, UI labels, metrics, and structured reports are English-first.

## TokenPatch and Aider

Aider is an interactive terminal pair programmer. TokenPatch is a bounded execution layer that sits alongside a primary coding agent. Choose Aider for an evolving coding conversation; choose TokenPatch when the requirement and allowed files are already known and you want checkpointed execution plus cost evidence. The tools can also be used together.

See the sourced comparison: [TokenPatch vs Aider](https://tokenpatch.com/compare/tokenpatch-vs-aider).

## BYOK First, Hosted Credits Later

The open-source client works today with your own DeepSeek API key.

Hosted tokenpatch.com credits are planned later for users who cannot easily get, recharge, or manage a DeepSeek key directly. The hosted path is optional and private beta first. tokenpatch should not be described as an official DeepSeek reseller or as endorsed by DeepSeek.

## Docs

- [Quickstart](docs/QUICKSTART.md)
- [Install Guide](docs/INSTALL.md)
- [Demo Evidence](docs/DEMO.md)
- [FAQ](docs/FAQ.md)
- [MCP Client Setup](docs/MCP_CLIENTS.md)
- [Integration Guide](docs/INTEGRATIONS.md)
- [Savings Estimates](docs/SAVINGS.md)
- [GitHub Publication Review](docs/GITHUB_PUBLICATION.md)
- [Public Release Manifest](docs/PUBLIC_RELEASE_MANIFEST.md)

## Common Commands

```bash
tokenpatch bootstrap
tokenpatch do "Implement a small change" --allowed-file path/to/file
tp do "Implement a small change" --allowed-file path/to/file
tokenpatch metrics
tokenpatch report
```

Advanced commands such as `plan`, `run`, `validate`, `review`, `checkpoint`, `memory`, `web`, and `mcp` are documented in the [Quickstart](docs/QUICKSTART.md) and [Install Guide](docs/INSTALL.md).

Compatibility note: legacy `mmdev` internals remain for older scripts, but the public project name is tokenpatch.

## Development

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