ProofFlow

English | 简体中文

Agent Work Ledger for AI coding.

Vibe coding is fast. Blind trust is not enough.

ProofFlow makes AI-generated work reviewable, traceable, and reversible by recording the full chain from work contract to proof packet: contract first, record the algorithm decision, declare the cost budget, snapshot the code state, bind claims to evidence, evaluate done criteria, then export an auditable packet.

Latest release: v0.1.8 - Agent Work Ledger for AI coding

▶ Watch the 72s demo: From AI agent claims to verifiable Proof Packets

Demo asset (deferred): The end-to-end dogfood Demo_Asset GIF and the VSCode_Channel inline audit / Approve Gate screenshots for the v0.1.x dogfood-and-channel-polish milestone are deferred to the next dogfood cycle (no capturable VS Code window in this milestone). Tracked in PLANS.md#vscode-channel-screenshots-deferred-from-v0-1-x-dogfood.

📦 Example Proof Packets: code review · issue triage · agent work ledger · ledger dogfood

Maintainer workflow: docs/maintainer_evidence_workflow.md

Agent Work Ledger guide: docs/agent_work_ledger.md

Ledger Risk Hints: docs/ledger_risk_hints.md

5-minute MCP quickstart: docs/ledger_quickstart_mcp.md

Ledger PR comment template: docs/examples/pr_comment_agent_work_ledger.md

AgentGuard semantic rules: docs/agentguard_semantic_rules.md

Agent Work Ledger

ProofFlow is not only a PR review helper. It is a local-first ledger for AI coding work. A Ledger Case captures the workflow before, during, and after an agent changes code:

1. Work Contract - record the objective, repo path, allowed scope, forbidden actions, required tests, done criteria, evidence requirements, algorithm requirements, and cost budget.
2. Algorithm Decision - record the selected approach, rationale, alternatives, invariants, and forbidden approaches before implementation.
3. Cost Budget - declare token, API, GPU, CPU, runtime, or iteration limits before expensive work begins.
4. Snapshot - capture the git diff, changed files, HEAD SHA, base ref, and diff hash so reviewers know exactly what code state was examined.
5. Evidence - store command output, test output, diffs, notes, screenshots, or other artifacts as searchable evidence.
6. Claim - require every agent claim to bind to evidence before it is trusted.
7. Evaluation - deterministically check required tests, algorithm decision, cost budget, scope boundaries, missing evidence, unaccepted risks, and non-blocking Risk Hints for suspicious routes.
8. Proof Packet - export the contract, algorithm decision, cost budget, timeline, snapshots, claims, evidence, evaluation, decisions, and remaining risks into markdown.

Main chain: Work Contract -> Algorithm Decision -> Cost Budget -> Snapshot -> Evidence -> Claim -> Evaluation -> Proof Packet. This keeps the core product invariant sharp: no Case, no workflow; no Evidence, no trusted Claim; no done criteria evaluation, no quiet success.

Risk Hints extend the evidence flow without turning ProofFlow into an automatic algorithm judge. They tell the maintainer when the recorded route may be wrong or too expensive, such as regeneration where mapping was required, budget overrun metadata, or tests that prove output but not method.

See docs/agent_work_ledger.md for the full architecture and evaluation model, or docs/ledger_quickstart_mcp.md to run the full MCP flow.

ProofFlow Reviewed ProofFlow

ProofFlow v0.1.6 was dogfooded on a real repository PR. The GitHub Actions workflow ran AgentGuard, posted a stable PR summary comment, uploaded summary.json, and exported a downloadable Proof Packet.

• Real PR: #94 Dogfood v0.1.6 CI review story
• Review run: ProofFlow PR Review #25953071865
• Patch release from dogfood feedback: v0.1.6.1
• Result: one stable comment updated across pushes, one artifact containing the Proof Packet and summary.json, no merge blocking.

Problem

AI coding agents (Claude Code, Codex, Copilot Workspace) can modify files, run commands, and make decisions autonomously. But there's no standard way to:

• Audit what an agent did and why
• Gate high-risk actions before they execute
• Prove that a code review actually checked what it claims
• Undo agent-initiated changes with confidence

ProofFlow solves this by sitting between the agent and the filesystem, creating an evidence graph that links every action to its justification.

Quickstart

Docker (recommended)

Run from the parent directory of the freshly cloned repo. The Push-Location / Pop-Location pair keeps the working directory at the repository root for the docker compose up command and restores it after the block, so this snippet is copy-paste safe in a single PowerShell session.

git clone https://github.com/Hyperion-GPU/ProofFlow-v0.1.git
Push-Location ProofFlow-v0.1
docker compose up
Pop-Location

Backend: http://localhost:8787 | Frontend: http://localhost:5173

Docker publishes both ports on 127.0.0.1 by default to preserve ProofFlow's localhost trust boundary. For stronger local protection, set an API key before starting:

PROOFFLOW_API_KEY=change-me docker compose up

If you enable backend auth for the Docker frontend, use the same PROOFFLOW_API_KEY value at build time so Vite can embed VITE_PROOFFLOW_API_KEY in the static frontend bundle. AgentGuard test_command execution is disabled by default; set PROOFFLOW_ENABLE_TEST_COMMANDS=true only when you intentionally want the backend to run local test commands during review.

Manual

Start each component from the repository root in a single PowerShell session. Push-Location / Pop-Location keeps the working directory predictable across the backend and frontend blocks; the backend port is fixed to 8787 to match the make dev-backend baseline. npm run dev is a long-running process - run the frontend block in a second PowerShell session if you want to keep the backend uvicorn process visible in the first.

# Backend
Push-Location backend
pip install -r requirements.txt
python -m uvicorn proofflow.main:app --port 8787
Pop-Location

# Frontend (long-running; recommended in a second PowerShell session)
Push-Location frontend
npm ci
npm run dev
Pop-Location

MCP Integration (Claude Code / Codex)

pip install proofflow-mcp

Add to your project's .mcp.json:

{
  "mcpServers": {
    "proofflow": {
      "command": "proofflow-mcp",
      "env": { "PROOFFLOW_BASE_URL": "http://127.0.0.1:8787" }
    }
  }
}

Now your AI agent can keep an Agent Work Ledger, scan files, review code, triage issues, suggest actions, and export audit reports - all with enforced safety gates.

Codex Maintainer Plugin

ProofFlow also includes a repo-local Codex plugin at plugins/proofflow-maintainer. It provides starter prompts and a maintainer-focused skill for:

• reviewing the current diff with ProofFlow,
• creating a Proof Packet for a PR,
• triaging issue text into a ProofFlow Case,
• keeping an Agent Work Ledger for complex code tasks.

The plugin uses the same local proofflow-mcp server and keeps the backend trust boundary at http://127.0.0.1:8787. See the public-safe Agent Work Ledger example for the expected handoff shape.

Architecture