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

Paranoia, a new open-source tool from developer subvertnormality, provides adversarial code reviews by running one frontier coding agent against another: it integrates with Claude Code to have Codex review code, or with Codex to have Claude Code review, using a local MCP server. The tool, which requires Python 3.11+, git, and a subscription to the reviewing agent's CLI, offers five tools including critique_branch, critique_plan, query, rebut, and arbitrate, and includes a convergence loop to iterate reviews until issues are resolved.

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 quickstart · The five tools the-five-tools · How reviews work: the convergence loop how-reviews-work-the-convergence-loop · Tool reference tool-reference · Output reference output-reference · Configuration configuration · Safety model safety-model · Development development 1. Prerequisites - Python 3.11+ and git on PATH - The reviewing agent's CLI, installed and signed in on a subscription: Codex CLI https://developers.openai.com/codex codex , ≥ 0.144 or Claude Code https://code.claude.com claude arbitrate needs both 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 review arbitrate both vendors independently repo 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 paranoiatoml ; 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 any BLOCKER / MAJOR / FATAL class still matches; computes the verdict in Python and appends it as the CONVERGENCE: 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. Pass lineage explicitly when the reviewed ref is not a branch a detached HEAD or a raw commit , where there is no stable key to derive. critique plan always requires an explicit lineage — 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 review-output plus a CONVERGENCE: trailer class-closure-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 supposed to achieve. Treated as a claim to verify, never a fact to accept focus engine , model , effort , web search Common arguments common-arguments converge: 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 returns FAILED rather than reporting agreement it cannot describe. Neutralizes the framing with an Opus agent — advocacy stripped, options equalized in detail — then has the other vendor 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 only path: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 return CONVERGED .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 with ADVISORY: human-owner is still CONVERGED . Enforcing it is your policy.The snapshot commit is unreferenced and SNAPSHOT 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. moved must 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 a files 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 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 | malformed: … | 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 , scoped git 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 grant Bash python3: and friends. This applies to the spawned reviewer subprocess only; it does not read, write, or affect your interactive claude sessions. Codex is covered by its OS-level sandbox, which no repo setting can loosen. - Isolated. Committed reviews run inside a throwaway git 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. In converge 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 next git worktree prune / git gc . Your working tree and index are never touched. One opt-in exception: arbitrate with retain snapshot: true creates refs/paranoia/arbitrate/<stamp so its evidence survives git gc . It is the only mode in the server that writes a ref. Remove one with git 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/ /subvertnormality/paranoia-local/blob/main/docs : , /subvertnormality/paranoia-local/blob/main/docs/class closure plan.md class closure plan.md , and /subvertnormality/paranoia-local/blob/main/docs/plan class closure proposal.md plan class closure proposal.md . /subvertnormality/paranoia-local/blob/main/docs/arbitration plan.md arbitration plan.md MIT © 2026 Andrew Hillel