Agent Proof

Agent Proof is a small TypeScript CLI for recording the checks run after a 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. Node.js 20 or later is required.

Quick start

git clone https://github.com/YusefSyed/agent-proof.git
cd agent-proof
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

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-09-24: 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.
• An empty allowedCommands list is valid and disallows every check.
• Validates the complete manifest before running anything: checks must be nonempty, have unique nonempty IDs, and use valid string, timeout, and output-limit fields.
• Applies a 30-second timeout and 1 MiB process buffer by default.
• Redacts common credential formats and exact project-specific values from all report text, including task, command metadata, and output.
• 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.

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, complete manifest validation before execution, and redaction/truncation across report metadata and output. GitHub Actions runs the same verification on pushes and pull requests.

License

MIT. See LICENSE.