Getting started

Install and run verify

paranoid is a single static binary. It needs git and no account or server.

Install

Binaries. Download 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).

Running verify

From inside a repository an agent has touched, run:

paranoid verify

Changes do not need to be committed. --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).

Checking the agent's summary

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 invocations

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 repository