Documentation

paranoid docs

Reference documentation for paranoid, a local CLI that audits agent-written diffs: every command, every flag, every rule, the report schema, and CI setup. For an overview of the tool, see the landing page.

What paranoid does

Point paranoid at 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 exits with a code you can gate CI on.

Everything runs locally. No telemetry, no account, no server. The only network use is optional dependency-registry lookups, and --offline turns those off too.

Where to start

Start here

Getting started

Install paranoid and run your first verify.

Command

verify & flags

Every flag on the main command, with defaults.

Reference

Rules

All seven categories, every rule ID, what each one catches.

Config

Team policy file

.paranoid.toml's four keys: thresholds, a disabled rule, sandbox image pins.

Exit codes & CI

Score thresholds, exit codes, and the GitHub Action.

Formats

Report & schema

The JSON report, its versioned schema, and SARIF output.

Adoption

Baseline & suppressions

Snapshot existing findings so only new ones fail CI.

Trend

History

Save reports over time and render a score trend as HTML.

Claims

Sessions & claims

Checking the agent's own summary against the diff, and which agents are supported.

Clean room

Sandbox & coverage

How the clean-room test rerun and coverage collection work.

Command

fix-prompt

Turn a report into a corrective instruction block for the agent.

Command

watch

Watch a repository and run static checks live, on every change.

Trust

Signing & attest

Sign a report, check it, a commit trailer, and a badge file.

Integrations

The GitHub Action, the pre-commit hook, and Claude Code.

Command reference at a glance

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 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, trust paranoid <command> --help over this page.

Source on GitHub · docs/rules.md (the canonical generated rule reference) · Apache-2.0