Show HN: Paranoia – Get a cold, adversarial review of your code

Get a cold, adversarial review of your code, your plans, and your decisions from the other frontier coding agent — running locally, on its own subscription, with full read access to your repository.

Install it into Claude Code and reviews are performed by Codex. Install it into Codex and reviews are performed by Claude Code. paranoia-local is the MCP server between them: it builds the prompt, runs the other agent read-only, and returns a structured critique.

┌──────────────┐   "paranoia: critique this branch"   ┌───────────────┐
│  Claude Code │ ───────────────────────────────────► │ paranoia-local│
│  (your work) │                                      │  (MCP, local) │
└──────────────┘                                      └───────┬───────┘
                                                              │ codex exec (read-only)
                                                      ┌───────▼────────┐
                                                      │  Codex / GPT-5 │ ← reads the repo,
                                                      │  cold reviewer │   decides what to open
                                                      └────────────────┘

Contents · Quickstart · The five tools · How reviews work: the convergence loop · Tool reference · Output reference · Configuration · Safety model · Development

1. Prerequisites

• Python 3.11+ and git

onPATH

• The reviewing agent's CLI, installed and signed in on a subscription: Codex CLI(codex

, ≥ 0.144)orClaude Code(claude

) arbitrate

needsboth CLIs; the four review tools need only the other one

2. Install

git clone https://github.com/subvertnormality/paranoia-local
cd paranoia-local
pip install -e .

3. Wire it into your agent. --engine

names the agent that performs reviews, which is the opposite one from the caller.

Into Claude Code (reviews performed by Codex)

claude mcp add paranoia -- paranoia-local --engine codex

Into Codex (reviews performed by Claude Code) — needs two extra keys

codex mcp add paranoia -- paranoia-local --engine claude

Then edit ~/.codex/config.toml

. Codex defaults to a 60-second tool timeout and a 10-second startup timeout; a review runs for minutes, so both must be raised or every call fails:

[mcp_servers.paranoia]
command = "paranoia-local"
args = ["--engine", "claude"]
tool_timeout_sec = 3600
startup_timeout_sec = 30

Verify with codex mcp get paranoia

.

4. Ask for a review.

"Use paranoia to critique this branch against main. Intent: add overdraft protection to

withdraw()

."

Your agent calls:

{
  "name": "critique_branch",
  "arguments": {
    "repo_path": "/Users/you/Work/my-project",
    "base_ref": "main",
    "round": 1,
    "diff_intent": "Add overdraft protection to withdraw()."
  }
}

You get back a five-section critique with severity-tagged findings, and a computed CONVERGENCE:

trailer telling you whether the loop may stop.

Tool	Use it to	Needs
critique_branch

repo_path

critique_plan

repo_path

• plan_text

| plan_path

query

question

rebut

session_ref

from that reviewarbitrate

both vendors independentlyrepo_path

, decision

, options

, stakes

Every review returns a session_ref

in its footer. Pass it to rebut

to reopen that exact reviewer session.

A single review is rarely the end of it. You review, you fix, you review again. paranoia-local models that as a convergence loop, and gives you four controls over it plus one computed signal that tells you when to stop.

round 1 ──► review ──► fix ──► round 2 ──► review ──► fix ──► round 3 ──► CONVERGED
             │                              │                              +
             └── already_raised ────────────┴── already_raised ────► CONVERGENCE: NOT-BLOCKED

Each round is a fresh, cold reviewer — it has no memory of the last one. You carry state forward with the arguments below.

The 1-based round number. Increment it every round. At round >= 3

the reviewer reports only merge-blocking findings and withholds [MINOR]

and [OUT-OF-SCOPE]

, writing CONVERGED

when none remain. This is the lever that makes a loop stop instead of grinding through diminishing findings.

round

is required on critique_branch

and critique_plan

unless you pass class_closure: false

.

The real deployment context, threat model, and scale the work operates in:

"stakes": "Internal booking API, single team, authenticated first-party callers, ~1k req/min."

The reviewer treats it as the boundary of legitimate concern. Findings that assume adversaries, scale, or failure modes beyond it are dropped or tagged [OUT-OF-SCOPE]

, never must-fix. Omit it and the reviewer assumes a modest internal tool; a review with no stakes ends with a STAKES: unstated

line. Pass stakes: "unstated"

to accept that reading deliberately and silence the line.

Set it once per project in .paranoia.toml; override per call to tighten it for a specific surface.

One-line, file:line

-cited claims you have already accepted from earlier rounds. The reviewer is told not to restate them and to hunt for what they missed. Pass the claim and its citation, never the previous reviewer's prose.

"already_raised": [
  "withdraw() ignores pending holds — accounts.py:88",
  "the overdraft test asserts the fee, not the balance — test_accounts.py:210"
]

On by default. A finding is usually an instance of a class: one violated invariant, several sites. Class closure makes the class itself a tracked object that survives the round.

The reviewer ends its review with a register block:

=== CLASS REGISTER ===
CLASS: every public writer must validate its input before the first mutation
SEVERITY: MAJOR
PATTERN: def (create|update)_[a-z_]+\(.*\):\n(?!.*validate)
PATHSPEC: src/

The server then, every round:

re-runs each registered regex itself against the reviewed snapshot (git grep

), and lists every surviving match to the next reviewer;refuses to report the loop unblocked while anyBLOCKER

/MAJOR

/FATAL

class still matches;computes the verdict in Python and appends it as theCONVERGENCE:

trailer.

A class closes when its predicate returns zero matches and reopens the moment it matches again. MINOR

and OUT-OF-SCOPE

classes are tracked but advisory — they never block.

Where no regex can express the invariant, the reviewer registers a PROCEDURE:

instead. Those are unmechanized: nothing re-runs them, they are shown to every later reviewer, and they close only when a reviewer explicitly writes CLOSED: <class-id>

.

On critique_plan, every class is unmechanized — a regex over prose closes as soon as the wording changes, so predicates are not accepted there at all. Plan closure gives you

non-forgetting plus explicit closure, not automatic recurrence detection.

Register transitions a reviewer can emit, besides a new class:

Record	Effect
CLOSED: <id>
An unmechanized class is judged closed
REOPEN: <id>
A closed unmechanized class is violated again
RECLASSIFY: <id> <severity>
Correct a severity
SUPERSEDE: <id> + BY: / WITH-PATTERN: / WITH-PROCEDURE:
Replace a class

You cannot emit these yourself — ask for them in focus

, e.g. "class 3f2a91c4 is registered MAJOR but its effect is cosmetic; reclassify it if you agree."

Class state lives in ~/.paranoia/lineages/<lineage>.json

.

critique_branch

derives the key from repo +base_ref

• reviewed branch. Passlineage

explicitly when the reviewed ref isnot a branch (a detached HEAD or a raw commit), where there is no stable key to derive.critique_plan

always requires an explicitlineage

— a plan has no branch, and nothing is derived from its text or path.

The key is used verbatim as the state filename with no namespacing, so make it globally unique and mode-qualified: myproject-42-plan

for a plan seam, myproject-42-branch

for the branch seam of the same work. A key already used by the other tool is refused rather than merged.

The stop condition is two-part:

• the computed trailer reads CONVERGENCE: NOT-BLOCKED

,and - the round returns CONVERGED

, or only[MINOR]

/[OUT-OF-SCOPE]

items.

When the two disagree, the trailer governs — and says so in its own output.

For a review with no loop behind it — a design sketch, a quick second opinion — pass class_closure: false

. That is the single escape, and it also drops the round

and lineage

requirements.

{ "repo_path": "/path/to/repo", "plan_text": "…", "class_closure": false }

When a registered regex matches a line that does not actually violate the invariant, exempt that exact line:

"exempt": [{
  "class_id": "3f2a91c4",
  "path": "src/app.py",
  "line": 17,
  "line_text": "    legacy_open(state)"
}]

line_text

must be byte-exact including indentation. The exemption is keyed on it and goes void the moment that line changes, so the match resurfaces. Every exemption is shown to every later reviewer, with the invariant attached, so it can be challenged; unexempt

takes the same class_id

/path

/line

and revokes one.

A match inside a binary blob cannot be exempted — narrow the class's PATHSPEC

instead.

Arguments marked required are enforced; everything else has the default shown.

Adversarial review of a git branch, a committed range, or the dirty working tree. Returns a five-section critique plus a CONVERGENCE: trailer.

Argument	Type	Default	Description
repo_path
string	required
Absolute path to the git repo
base_ref
string	main
Base ref for the diff
head_ref
string	HEAD
Head ref to review
round
integer	required unless class_closure: false
1-based round number; must be an integer ≥ 1
include_uncommitted
boolean	false
Review the dirty working tree vs HEAD instead of a committed range. Runs in the live repo, not a worktree
isolate
boolean	true
Review inside a throwaway worktree of head_ref . Ignored for uncommitted reviews
converge
boolean	true
Pre-gather a deterministic evidence packet (every touched file in full, plus the diff) and review it against an immutable materialized snapshot. Always materializes, overriding isolate
max_packet_chars
integer	400000
Character budget for that packet. already_raised is always preserved; only file evidence is trimmed
class_closure
boolean	true
Track defect classes across rounds. false is the one-shot mode
lineage
string	derived	Explicit class-closure key. Required when the reviewed ref is not a branch
exempt / unexempt
array	—	Mark or revoke false positives of a class's regex — see

stakes

already_raised

[]

project_summary

diff_intent

supposedto achieve. Treated as a claim to verify, never a fact to acceptfocus

engine

, model

, effort

, web_search

Common argumentsconverge: false

falls back to a legacy in-place review that has no class closure, so it must be paired with class_closure: false

.

Adversarial review of a plan or design document. The reviewer reads the real code to test every premise the plan makes about current behaviour. Returns the same five sections, tagged [FATAL]

/[MAJOR]

/[MINOR]

/[OUT-OF-SCOPE]

.

Argument	Type	Default	Description
repo_path
string	required
The repo the plan concerns
plan_text
string	one of these two
The plan as markdown
plan_path
string	one of these two
Absolute path to a markdown plan file
round
integer	required unless class_closure: false
1-based round number
lineage
string	required unless class_closure: false
Globally unique, mode-qualified key. Nothing is derived
class_closure
boolean	true
Unmechanized classes only. false is the one-shot mode
context
string	—	Background the reviewer needs to judge the plan fairly
focus
string	—	Narrow the review to a specific concern
stakes
string	—	The scope boundary
already_raised
array	[]
Claims already accepted from prior rounds
engine , model , effort , web_search
—	see

class_closure

and lineage

are call arguments only here — .paranoia.toml

is not consulted for either.

One question, one answer. Not a full review: no five-section scaffold, lower reasoning effort by default. The reviewer reads the repo (when given one) and returns a direct answer, citations, and a stated confidence level.

Argument	Type	Default	Description
question
string	required
The specific question to double-check
repo_path
string	—	Repo to ground the answer in
files
array	[]
{path, reason?} hints to look at first — hints, not a payload; it can read anything
focus
string	—	Extra framing for the question
engine , model , effort , web_search
—	effort defaults to medium

Dispute one finding from a review. Resumes that same reviewer session with your counter-evidence, so it is cheaper and higher-resolution than a fresh round. The reviewer replies CONCEDE

or HOLD

with fresh citations.

Argument	Type	Default	Description
repo_path
string	required
Same repo the review ran against
session_ref
string	required
From the prior review's footer
rebuttal
string	required
Your counter-evidence
engine , model , effort , web_search
—	see

Decides between 2–4 options. Both frontier vendors judge independently and cold over one pinned snapshot, and Python computes the verdict.

{
  "repo_path": "/Users/you/Work/my-project",
  "decision": "Choose the numeric type for the position-size threshold.",
  "options": [
    {"id": "opt-float",   "statement": "Store it as a float."},
    {"id": "opt-decimal", "statement": "Store it as a Decimal."}
  ],
  "stakes": "Internal CLI, single team, threshold used only in a log line.",
  "files": [{"path": "scripts/lib/registry.py", "reason": "the writer"}]
}

What it does, in order:

Pins one snapshot. Each decider gets its own worktree of the same commit. Git refs and the reflog are digested before and after; if anything moved, the run returnsFAILED

rather than reporting agreement it cannot describe.Neutralizes the framing with an Opus agent — advocacy stripped, options equalized in detail — then has theothervendor attest that field by field.stakes

is passed through verbatim, never rewritten.Counterbalances presentation. One decider sees canonical order, the other reversed, under opaque per-decider labels. Neither is told the other exists.Computes the verdict. No model adjudicates the adjudication.On divergence, runs one reconciliation round carrying onlypath:line

citations and bytes the server itself read — never the other model's prose — and only when there is genuinely novel evidence.

Argument	Type	Default	Description
repo_path
string	required
Every decisive citation must be repo-verifiable
decision
string	required
What is being decided (max 2500 chars) — not the evidence for it
options
array	required
2–4 mutually exclusive {id, statement} . Array order is irrelevant; canonical order is derived by sorting ids
stakes
string	required
Pass "unstated" to accept a fixed default reading
context
string	—	Shared facts and the full specification of whatever only one option adopts (max 20000 chars)
files
array	[]
{path, reason?} starting points. Both deciders see the same list
subject
string	—	Short label for the paste-ready record block
clean
boolean	true
Run the cleaner and its cross-vendor attestation
models
object	—	{codex?, claude?} per-vendor overrides
cleaner_model
string	claude-opus-5
Override the cleaner model
order_seed
string	—	Replay a previous run's ORDER-SEED to reproduce its labels and ordering
retain_snapshot
boolean	false
Create refs/paranoia/arbitrate/<stamp> so evidence survives git gc
effort , web_search
—	see

** arbitrate has no engine or model** — it drives both vendors, so a single override could only degrade it to one of them or send one vendor's model name to the other CLI.

Input bounds, checked before anything is spent:

Bound	Limit
option statement	1200 chars
longest ÷ shortest option	2.0
decision
2500 chars
context
20000 chars

The shape that passes these naturally: put every shared fact, and the full specification of whatever only one option adopts, into context

— prefaced as "the rules under consideration, if adopted". Leave each option statement to say only how much of it is adopted and what follows. ~800 chars each is typical.

Behaviour worth knowing before you rely on it:

It only decides what the repository can settle. A converging vote must cite a line that resolves. A decision that does not turn on repo-verifiable grounds will never returnCONVERGED

.Each decider reports whether it judges that a named human owner should be authorizing the decision. That is reported, never gated:ADVISORY

does not block.CONVERGED

withADVISORY: human-owner

is stillCONVERGED

. Enforcing it is your policy.The snapshot commit is unreferenced andSNAPSHOT

is provenance, not a replay handle.git gc

reclaims it. The audit log holds both prompts, both replies, and the carried evidence.retain_snapshot: true

pins it behind a ref.On divergence, only a decider that One that held its round-1 position needs only a citation that resolves — provided its round-1 decisive citation resolved too. A holder that was never substantiated must ground in gained evidence like a mover.movedmust ground in the carried evidence.Bias is reduced, not eliminated. Order counterbalancing equalizes mean rank but not higher moments for 3–4 options; attestation is a model's judgement, not a proof; and afiles

list pointing only at evidence favouring one option biases both deciders identically.docs/arbitration_plan.md

§2 enumerates the residuals.

Accepted by the four review tools:

Argument	Values	Default
engine
codex	claude
the server's configured engine
model
any model name	the engine's strongest: gpt-5.6-sol / claude-fable-5
effort
low	medium	high
high (query : medium )
web_search
boolean	true

Every review returns exactly five sections, in this order:

Section	Contains
## What works
Specific correct decisions, cited. "Nothing notable." when there are none
## What doesn't work
Actual defects: quoted lines, failure mechanism, observable symptom. Worst first
## Risks
Failure modes the author didn't consider that the code is exposed to
## Gaps
What the change should do to reach its stated intent but doesn't
## Improvements
Concrete changes that alter the outcome under the stated stakes

Every item in the last four sections carries exactly one severity tag:

Code review	Plan review	Meaning
[BLOCKER]
[FATAL]
Ships a bug / kills the plan as written
[MAJOR]
[MAJOR]
Fix before merge / before execution
[MINOR]
[MINOR]
Fix opportunistically
[OUT-OF-SCOPE]
[OUT-OF-SCOPE]
Real, but beyond the stated stakes — file separately

A finding that recurs from a tracked class is marked [RECURRENCE <class-id>]

next to its severity tag.

The footer carries the session_ref

for rebut.

Appended below the review whenever class closure ran:

LINEAGE: 9f2c1a4b0e77 (rounds recorded: 8)
CLASS-REGISTER: parsed 1
CLASS-CLOSURE: 1 open, 2 closed, 3 surviving matches, 0 exempt, 1 unmechanized
CONVERGENCE: BLOCKED — 1 class(es) unclosed:
  3f2a91c4 every public writer must validate before the first mutation (mechanized: 3 match(es))

Line	Meaning
CONVERGENCE: NOT-BLOCKED
No blocking class is unclosed. Advisory classes may remain open
CONVERGENCE: BLOCKED
Named classes are still open; any CONVERGED in the review above is void
CLASS-REGISTER: NONE	parsed N
What the reviewer's register block contained
CLASS-CLOSURE-WARNING: … closed in the round it was registered
The predicate matched nothing at birth — usually too narrow. Ask the next reviewer to SUPERSEDE it
BLOCKED — register debt from round N
Two attempts at a parseable register failed. The next round with a good register clears it
unmechanized: awaiting reviewer CLOSED or RECLASSIFY
A semantic class no regex can check
STATE-UNAVAILABLE
Lineage state is unreadable, unwritable, or a previous write may not have completed. The message names the absolute path; repair or delete it, then re-run

NOT-BLOCKED

asserts only that no blocking class is unclosed. It never asserts the change is correct — the reviewer's findings still govern that.

Outcome	Meaning
CONVERGED
Unanimous, unblocked, and each vote substantiated by a resolved citation
BLOCKED
They agree on an option and one of them tags it [MAJOR] /[FATAL]
REFRAME_REQUIRED
A decider surfaced a better unlisted option. Give it an id and re-run
UNRESOLVED
Still split, or agreement nobody could substantiate
FAILED
Preflight, cleaning, parsing, or the repo's refs moved mid-run

The reply ends with a machine-readable trailer whose fields are always present: ARBITRATION

, SELECTED

, ADVISORY

, AUTHORITY-POLICY

, CLEANING

, SNAPSHOT

, ORDER-SEED

, REFS-MOVED

, AUDIT

, ROUNDS

.

Drop one at the repo root so callers stop retyping context. Keys go at the top level or under [paranoia]

. Precedence: call argument > .paranoia.toml > built-in default.

project_summary = "A booking API. Python/FastAPI, Postgres. Auth via short-lived JWTs."
base_ref = "develop"
stakes = "Internal booking API, single team, authenticated first-party callers, ~1k req/min."
web_search = true
isolate = true

Honoured keys: base_ref

, project_summary

, stakes

, isolate

, converge

, class_closure

, max_packet_chars

, model

, effort

, web_search

.

critique_plan

's class_closure

and lineage

are not read from here.

paranoia-local --engine {codex|claude} [--log-dir DIR]

Flag	Default	Description
--engine
required
Which local engine performs reviews — the other agent from the caller
--log-dir
~/.paranoia/logs
Audit-log directory

Path	Contents
~/.paranoia/logs/
One JSON audit record per call: engine, model, round, already_raised , session ref, timings, and the review text
~/.paranoia/lineages/
Class-closure state, one file per lineage

Lineage state deliberately does not follow --log-dir

, so moving your logs cannot silently reset a tracked lineage. Set PARANOIA_STATE_ROOT

to relocate it.

Read-only. Codex runs under its OS sandbox (--sandbox read-only

); Claude runs with a read-only tool allowlist (Read

,Grep

,Glob

, scopedgit

reads, web search) and write tools explicitly denied. The reviewer cannot edit your code, run your test suite, or reach the network except for opt-in web search. - The audited repo cannot widen the reviewer. The Claude engine is spawned with--setting-sources ""

, so it loads no.claude

settings files — otherwise the reviewed repo's.claude/settings.local.json

and your global settings would merge on top of the allowlist, and those routinely grantBash(python3:*)

and friends. This applies to the spawned reviewer subprocess only; it does not read, write, or affect your interactiveclaude

sessions. Codex is covered by its OS-level sandbox, which no repo setting can loosen. - Isolated. Committed reviews run inside a throwawaygit worktree

of the target ref, so they never collide with your working tree and can review a branch that isn't checked out. Dirty-working-tree reviews necessarily run in the live repo, read-only. - No API keys, no telemetry. The server shells out to a CLI you are already signed into. - Minimal footprint. Inconverge

mode the server creates a short-lived worktree and a few unreferenced git objects in the target repo. Both are cleaned up on exit and no ref is created. A hard crash can leave the worktree registration until the nextgit worktree prune

/git gc

. Your working tree and index are never touched.One opt-in exception:arbitrate

withretain_snapshot: true

createsrefs/paranoia/arbitrate/<stamp>

so its evidence survivesgit gc

. It is the only mode in the server that writes a ref. Remove one withgit update-ref -d <ref>

.

Reviews draw on your subscription's agentic-usage pool, and a convergence loop is many agent turns. Use query

for quick checks and reserve multi-round critique_branch

loops for changes that warrant them.

arbitrate

is the expensive one and the only tool that spends from both subscriptions in a single call: typically 4 agent turns, 8 at worst (a cleaning retry plus a reconciliation round).

pip install -e '.[dev]'
python -m pytest        # unit + integration; integration uses fake CLIs, no quota

The engine subprocess boundary is dependency-injected, so the whole stack is unit-tested without spending subscription quota. A separate integration test drives the real subprocess runner against fake codex

/claude

binaries on PATH

.

Design documents for the two non-obvious subsystems live in docs/:

,

class_closure_plan.md

, and

plan_class_closure_proposal.md

.

arbitration_plan.md

MIT © 2026 Andrew Hillel

source & further reading

github.com — original article