# ProofFlow

Keeps a local ledger of what an AI agent did: contract, code snapshots, evidence and a check of done criteria. Useful when you need to prove the work matches the claim.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 7
- Author: Hyperion-GPU
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Hyperion-GPU/ProofFlow-v0.1
- Updated: 2026-08-08
- HTML: https://affpapa.org/en/nevibecode/mcp/proofflow

## What it does

ProofFlow records the chain that runs from a work contract to a proof packet. An agent first writes down the objective, the repo path, what it may and may not touch, the tests it must run and the criteria for done. Then come the algorithm decision, a declared cost budget, a snapshot of the code state, evidence, and claims bound to that evidence. The finish is a deterministic evaluation and a markdown export.

Eight steps make up the flow: contract, algorithm decision, cost budget, snapshot, evidence, claim, evaluation, proof packet. The rule is blunt — no case means no workflow, and a claim without evidence is not trusted. Risk hints flag routes that look wrong or too costly, though the server does not act as an automatic judge of your algorithm.

You need `uvx` and a `PROOFFLOW_API_KEY`; the base URL goes in `PROOFFLOW_BASE_URL`. Without the key the server will not start, so set it in your environment first. A Docker route also exists, run from the root of the cloned repository.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `PROOFFLOW_BASE_URL`, `PROOFFLOW_API_KEY` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env PROOFFLOW_BASE_URL=<PROOFFLOW_BASE_URL> --env PROOFFLOW_API_KEY=<PROOFFLOW_API_KEY> --transport stdio proofflow -- uvx proofflow-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from proofflow-mcp <command>

### Codex

**Platform CLI**
```bash
codex mcp add proofflow --env PROOFFLOW_BASE_URL=<PROOFFLOW_BASE_URL> --env PROOFFLOW_API_KEY=<PROOFFLOW_API_KEY> -- uvx proofflow-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from proofflow-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "proofflow": {
            "command": "uvx",
            "args": [
                "proofflow-mcp"
            ],
            "env": {
                "PROOFFLOW_BASE_URL": "<PROOFFLOW_BASE_URL>",
                "PROOFFLOW_API_KEY": "<PROOFFLOW_API_KEY>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from proofflow-mcp <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "proofflow": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "proofflow-mcp"
            ],
            "env": {
                "PROOFFLOW_BASE_URL": "<PROOFFLOW_BASE_URL>",
                "PROOFFLOW_API_KEY": "<PROOFFLOW_API_KEY>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from proofflow-mcp <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e PROOFFLOW_BASE_URL=<PROOFFLOW_BASE_URL> -e PROOFFLOW_API_KEY=<PROOFFLOW_API_KEY> proofflow uvx proofflow-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from proofflow-mcp <command>

## When to use it
- record which files an agent actually changed
- tie an agent's claim to test output
- declare a token and runtime budget before costly work
- check done criteria before a quiet success
- export a proof packet for a reviewer

## Example prompts
- Open a ProofFlow ledger case for this task and record the contract
- Bind the agent's claim to the test output in ProofFlow
- Export a ProofFlow proof packet from the latest snapshot

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md