Getting started

Install and run your first verify

paranoid is a single static binary. No account, no server, no setup beyond installing it and having git on your machine.

Install

Binaries. Grab the archive for your platform from Releases (Linux amd64/arm64, macOS amd64/arm64, Windows amd64).

Install script.

curl -fsSL https://raw.githubusercontent.com/alainrk/paranoid/main/scripts/install.sh | sh

Go install.

go install github.com/alainrk/paranoid/cmd/paranoid@latest

From source. Clone the repo, then make build (needs Go 1.26 or later and git 2.30 or later).

Run it

From inside a repository an agent has touched, run:

paranoid verify

You do not need to commit anything first. --head defaults to your working tree exactly as it sits on disk, uncommitted and staged changes included. --base defaults to the merge-base with your default branch, or HEAD~1 if there is no default branch to compare against.

$ paranoid verify

paranoid v0.1.0
repo: /home/you/project
base: 7db5cfbeaacf
head: worktree (uncommitted changes included)

score: 40/100  verdict: fail

dependencies (1 finding)

  DEP001  critical  requirements.txt:2
      The new dependency requests-toolkit-pro does not exist in PyPI.

test-integrity (2 findings)

  TI001  critical  test_division.py
      A test file that existed at base is deleted at head.

  TI004  high  test_addition.py:10
      A skip was added to an existing test.

head: worktree (uncommitted changes included) means your working tree as it is on disk. The exit code follows the verdict (see Exit codes & CI), so the same command gates CI.

Check the agent's summary too

Add --claims summary.md (any free-text file) or --session <file> (an agent session file; see Sessions & claims for the full list of supported agents). With neither flag, claims are read from the git range's commit messages.

Common ways to run it

Both --base and --head accept anything git rev-parse resolves: a branch, a tag, a SHA, HEAD~3, origin/main.

Situation	Command
Nothing committed yet	paranoid verify
Before merging a feature branch	paranoid verify --base main
One specific commit	paranoid verify --base abc1234~1 --head abc1234
Last 30 commits	paranoid verify --base HEAD~30 --head HEAD
Between two releases	paranoid verify --base v0.3.0 --head v0.4.0
A teammate's unfetched branch	git fetch origin paranoid verify --base origin/main --head origin/agent-branch

Adopting on an existing repo

On a repository that has never run paranoid, verify reports every finding in the range, not only the latest change. Run paranoid baseline once to snapshot the current findings; later runs then only fail on new ones. See Baseline & suppressions.