AgentProof

AgentProof is a small CLI for turning coding-agent work into review-ready proof.

It starts with a narrow, practical problem: when an AI coding agent opens or updates a pull request, reviewers need to know what changed, what was verified, and which risks remain. AgentProof inspects the Git repository and produces a concise Markdown evidence block that can be pasted into a PR body, review comment, handoff note, or agent work log.

The long-term ambition is bigger: build an open engineering layer for agent construction, agent evaluation, and proof-carrying workflows for software agents and, eventually, physical-AI systems.

Why

AI agents are getting better at doing work, but useful work still needs evidence:

• Was the branch up to date?
• Was the working tree clean?
• Which files changed?
• Which checks actually ran?
• Is the proof easy for a human reviewer to inspect?

AgentProof is designed around a simple principle:

Agents should not just claim completion. They should carry proof.

Install

npm install -g agentproof

During early development, run from a local checkout:

npm install
npm link
agentproof --help

Usage

Generate proof for the current repository:

agentproof

Include verification commands that you ran:

agentproof \
  --command "npm test" \
  --command "npm run lint"

Write the proof to a file:

agentproof --out proof.md

Inspect another repository:

agentproof --cwd ../openclaw --command "pnpm test"

Example output

## AgentProof

### Repository

- Root: `/path/to/repo`
- Branch: `fix/example`
- HEAD: `abc1234`
- Upstream: `origin/main` (1 ahead / 0 behind)

### Preflight

- ✅ Working tree is clean
- ✅ Branch is not behind origin/main
- ✅ 1 commit(s) ahead of origin/main

### Verification commands

- `npm test`

> Generated by AgentProof. Review before pasting into a PR.

Roadmap

0.1 — PR proof CLI

• Git branch, upstream, ahead/behind, and working-tree preflight
• Changed-file and diff-stat summary
• Human-reviewable Markdown output
• Repeatable verification command recording

0.2 — Agent evaluation logs

• Structured run manifest for agent attempts
• Check result capture with exit codes and elapsed time
• Failure classification: environment, test, lint, product decision, auth, stale branch
• JSON output for dashboards and CI

0.3 — Agent-building workbench

• Reusable task specs for coding agents
• Guardrails for destructive operations and secret hygiene
• Handoff packets for multi-agent review
• Templates for PR body, maintainer comment, and daily engineering journal

0.4 — Physical-AI proof patterns

Physical AI work needs even stronger evidence than software-only work. AgentProof will explore proof templates for:

• Simulation run metadata
• Dataset / scene / seed provenance
• Safety envelope and rollback notes
• Real-world execution gates where humans must approve action

This part will be conservative by design: AgentProof should help document and evaluate physical-AI workflows, not encourage unsafe autonomous deployment.

Popular-project strategy

The goal is to make AgentProof useful enough to earn adoption, not to chase stars directly. The path to a 10,000-star-quality project is:

1. Solve a painful, recurring problem for real agent builders.
2. Keep the first CLI tiny and dependable.
3. Publish clear examples from real open-source contribution workflows.
4. Add integrations only after repeated evidence of need.
5. Treat safety, reviewability, and reproducibility as core features.

License

MIT