paranoidparanoid docs
Reference documentation for paranoid, a local CLI that audits agent-written diffs. It covers commands, flags, rules, the report schema, and CI setup. For an overview of the tool, see the landing page.
What paranoid does
paranoid takes a git range: the commit before the agent worked and the commit (or working tree) after. It analyzes the diff for deleted or weakened tests, dependencies that do not exist, swallowed errors, removed public symbols, disabled safety controls, and claims not backed by the change. It can also rerun the test suite in a container with no network. It prints a report with a 0 to 100 score and sets an exit code for use in CI.
Everything runs locally. There is no telemetry, account, or server.
The only network use is optional dependency-registry lookups.
--offline disables them.
Contents
Getting started
Install paranoid and run verify.
Commandverify & flags
Every flag on the main command, with defaults.
ReferenceRules
All seven categories, every rule ID, what each one catches.
ConfigTeam policy file
.paranoid.toml's four keys: thresholds, a disabled rule, sandbox image pins.
CIExit codes & CI
Score thresholds, exit codes, and the GitHub Action.
FormatsReport & schema
The JSON report, its versioned schema, and SARIF output.
AdoptionBaseline & suppressions
Snapshot existing findings so only new ones fail CI.
TrendHistory
Save reports over time and render a score trend as HTML.
ClaimsSessions & claims
Checking the agent's own summary against the diff, and which agents are supported.
Clean roomSandbox & coverage
How the clean-room test rerun and coverage collection work.
Commandfix-prompt
Render a report as a corrective instruction block for the agent.
Commandwatch
Watch a repository and run static checks on every change.
Commandformal
Lock theorem statements and see proof holes in Lean and Rocq files.
TrustSigning & attest
Sign a report, check it, a commit trailer, and a badge file.
CIIntegrations
The GitHub Action, the pre-commit hook, and Claude Code.
Command summary
| Command | What it does |
|---|---|
| paranoid verify [path] | Run the audit. The main command. |
| paranoid fix-prompt [path] | Render findings into a corrective instruction block. |
| paranoid baseline [path] | Write current findings to .paranoid-baseline.json. |
| paranoid history [path] | Render a score-over-time trend from reports saved by verify --save. |
| paranoid watch [path] | Watch a repository and run static checks on every change. |
| paranoid formal lock|unlock|status | Pin theorem statements in .paranoid-specs.json and list proof holes. |
| paranoid mcp | Run an MCP server over stdio exposing verify as a tool. |
| paranoid attest keygen | Generate a local ed25519 signing key. |
| paranoid attest verify | Check a report signed by verify --sign. |
| paranoid rules | List all rules with descriptions. |
| paranoid version | Print version, commit, and build date. |
| paranoid completion | Print a shell autocompletion script. |
Every command's flags are taken from its own --help
output in this repository, on the branch this page describes.
If your installed build behaves differently, use
paranoid <command> --help as the reference.