Skip to content
PatchArc

How to prove what your AI coding agent actually did

An agent made forty commits while you were in a meeting. Here is how to turn that into a record a reviewer can verify offline, using only Git and a CLI, and what the record does not cover yet.

PatchArc5 min read

The uncomfortable part of working with a coding agent is not that it writes code. It is that by the time you open the pull request, nobody can say with confidence what happened in between: which attempt was reverted, which decision was deliberate, which test was regenerated rather than read. The diff is the end state. The story is gone.

This guide shows how to keep the story with the change, in a form a reviewer can verify without trusting you or the agent. It uses patcharc 0.2.0 and nothing else. It also says plainly what the record does not contain yet.

What "prove" can mean here

Three different claims get bundled into "prove what the agent did":

  1. Integrity: the record you are reading is the record that was produced, unedited.
  2. Provenance: these commits, in this order, with these files touched.
  3. Intent: why each call was made, and what risk was knowingly left.

A signed capsule gives you the first two outright. The third only exists if someone writes it down while it is true. PatchArc makes that a one-line command so it actually happens.

Step 1: initialize once per repository

$ patcharc init
✓ Initialised PatchArc in /Users/you/src/your-repo
  config:   .patcharc/config.yaml
  key:      .patcharc/keys/arc-signing.ed25519 (mode 0600)
  database: .patcharc/session.db

This creates a fresh Ed25519 key (never committed; init adds it to .gitignore) and a local SQLite store. No account, no network.

Step 2: start an Arc before the agent starts

$ patcharc start --detach "Agent: migrate auth tests from jest to vitest"
✓ Arc arc_8f2c1d4a9b started on main @ a1b2c3d
  observer: detached (PID file: .patcharc/observer.pid)

Use --detach. The observer polls Git plumbing every 1.5 seconds and records each new commit and the files it touched. It installs no hooks and never writes to your working tree, which matters when an agent is also writing to it.

Then tell the agent to commit in small steps. Each commit becomes a row in the record; one giant commit at the end becomes one row.

Step 3: write down the decisions while they are decisions

The agent proposes something. You accept it, reject it, or accept it with a caveat. Record that in the moment:

$ patcharc decision "Keep the legacy test helpers; agent's rewrite rejected for now"
✓ decision recorded
$ patcharc risk "Snapshot files were regenerated, not reviewed line by line"
✓ risk recorded

If you use Claude Code, you can put these two commands in your CLAUDE.md so the agent records its own decisions; the observer captures the events either way.

Step 4: stop, and read what you sealed

$ patcharc stop
✓ Arc sealed: .patcharc/capsules/arc_8f2c1d4a9b.parc
$ patcharc verify .patcharc/capsules/arc_8f2c1d4a9b.parc
✓ arc_8f2c1d4a9b is valid (14 files, 71302 bytes, signed by 3f9a1c7e2b5d…)

The capsule is a ZIP with a canonical-JSON manifest that lists every file with its SHA-256, an Ed25519 signature over that manifest, and the public key. Inside: the six-section review, one JSON record per commit, each commit's patch, and the scope index. Read it before you share it:

$ unzip -p .patcharc/capsules/arc_8f2c1d4a9b.parc evidence/summary/review.json | jq '{goal, decisions, risks}'

Step 5: hand it to the reviewer

Two options. Attach the .parc to the pull request; the reviewer runs patcharc verify and knows the record is intact. Or share a link:

$ patcharc login
$ patcharc share --visibility public
  ArcLink: https://patcharc.dev/a/X9kQ2mN4vR7s

The cloud re-verifies the signature and every hash with an independent implementation before it will publish the link. A capsule that fails verification is never served.

What this proves, precisely

  • That the commits listed were observed on this machine in this order, with these patches. (Trust level: observed.)
  • That the decisions and risks were recorded at those timestamps. (Trust level: declared; they are your words.)
  • That none of it changed after sealing.

It does not prove the commits exist on your remote, that the agent's reasoning was sound, or who holds the key. Identity comes from the account that uploaded the capsule, not from the signature. The trust model page spells this out.

What 0.2.0 does not capture

Be clear with your reviewer about these, because the gap is where people over-trust a record:

  • The transcript. Prompts and tool calls are not recorded; commits are. If the transcript matters, pair PatchArc with a transcript tool and reference it in a note.
  • Test results. Test-output parsing is not built; the Verification section reads zero. Put the numbers in a note: patcharc note "vitest: 212 passed, 0 failed".
  • Secret redaction. The engine ships but is not applied at seal. Read the patches before a public share.

Why not just sign commits?

Do both. A signed commit proves authorship of one commit. A capsule proves a review and its evidence across many commits, including the things that never became commits: the rejected proposal, the flagged risk. They answer different questions; the signing comparison puts them side by side.

ai-agentsverificationclaude-codecodexguide