Agent Proof

Agent Proof is a small TypeScript CLI for recording the checks run after an agent-assisted code change. A reviewer chooses the commands; Agent Proof runs them and writes local JSON and Markdown reports.

It has no runtime dependencies, does not call an AI service and does not send code anywhere.

Availability

Version 0.1.0 is intended to be cloned and run from source; it is not a published npm package. Its package.json has "private": true, so npm will not publish this checkout.

Current verification

The dated verification record documents the commands run against this checkout on 2026-07-27: typechecking passed, all five tests passed, and the production-dependency audit reported zero vulnerabilities. It is a point-in-time record, not a claim about future clones, dependencies, or environments.

What it records

For each check, the report includes:

• command and arguments
• working directory
• status and exit code
• duration
• captured stdout and stderr
• overall pass/fail status

The report proves only that those commands ran in that environment. It does not prove that the implementation is correct or replace code review, security analysis or product testing.

Safety boundaries

• Uses Node's execFile with shell: false; arguments are never interpolated into a shell command.
• Runs a command only when its executable appears exactly in allowedCommands.
• Applies a 30-second timeout and 1 MiB process buffer by default.
• Redacts common credential formats and exact project-specific values before writing reports.
• Truncates captured output to 12,000 characters by default.

Agent Proof is not a sandbox. Use it only with trusted manifests, commands, working directories and environments. Do not place credentials in arguments or intentionally print an environment containing secrets.

Quick start

npm ci
npm run example
cat evidence/evidence.md

To run a manifest directly:

npm run build
node dist/src/cli.js run examples/manifest.json --out evidence

Manifest

examples/manifest.json is a complete starting point.

{
  "version": 1,
  "task": "Verify the local TypeScript project before review",
  "allowedCommands": ["npm", "node"],
  "redact": ["a-value-that-must-never-appear-in-evidence"],
  "maxOutputChars": 12000,
  "checks": [
    {
      "id": "typecheck",
      "command": "npm",
      "args": ["run", "typecheck"],
      "timeoutMs": 60000
    }
  ]
}

Keep allowlists narrow. cwd, when provided, is resolved by Node relative to the process running Agent Proof.

Reports

The selected output directory receives:

• evidence.json — machine-readable evidence report.
• evidence.md — a reviewer-friendly report with each command's result and captured output.

The CLI exits 0 when every check passes, 1 when a check fails, times out or is disallowed, and 2 for invalid input or invocation.

Sample evidence excerpt

This is the kind of concise result a reviewer sees in a generated report (values vary by run):

## typecheck: PASSED
- Command: `npm run typecheck`
- Exit code: 0

The complete generated report includes the working directory, duration, stdout, and stderr; review it before relying on a result.

Development

npm ci
npm run typecheck
npm test
npm audit

The test suite covers passing and failing checks, timeouts, disallowed commands, and redaction/truncation. GitHub Actions runs the same verification on pushes and pull requests.

License

MIT. See LICENSE.