paranoia

# Paranoia Get a cold, adversarial review of your code, plans, and technical decisions from the other frontier coding agent. Paranoia Local is an MCP server that connects Claude Code and Codex CLI. Install it in one agent and it runs the other as a read-only reviewer, using that reviewer's existing subscription and full repository context. ```text Claude Code ──MCP──> Paranoia Local ──read-only──> Codex Codex ──MCP──> Paranoia Local ──read-only──> Claude Code ``` Use it to: - review a branch, diff, or dirty working tree; - challenge a plan against the code it describes; - track findings and defect classes until they are closed; - verify load-bearing plan claims against captured authoritative sources; - ask a focused repository question; - rebut a finding in the same reviewer session; or - arbitrate a decision with both vendors independently. [Get started](#quickstart) · [Choose a tool](#choose-a-tool) · [Understand tracked reviews](#tracked-reviews) · [Configure](#configuration) · [Full tool reference](docs/tool-reference.md) · [LLM and agent entry point](llms.txt) ## Quickstart ### 1. Install the prerequisites You need: - Python 3.11 or later; - Git 2.36 or later on `PATH`; and - the reviewing agent's stable CLI, installed and signed in: [Codex CLI](https://developers.openai.com/codex) 0.144.6 or later, or [Claude Code](https://code.claude.com) 2.1.251 or later. Default tiered Codex review also needs a CLI that offers the `gpt-6.1-sol` correction model; see [model routing](#tracked-reviews). Most tools need only the reviewer CLI. `arbitrate` uses both vendors and needs both CLIs. ### 2. Install Paranoia Local ```bash git clone https://github.com/subvertnormality/paranoia-local cd paranoia-local pip install -e . ``` ### 3. Add it to your coding agent `--engine` names the agent that performs the review, so it is the opposite of the agent you are configuring. #### Claude Code: reviews performed by Codex ```bash claude mcp add paranoia -- paranoia-local --engine codex ``` #### Codex: reviews performed by Claude Code ```bash codex mcp add paranoia -- paranoia-local --engine claude ``` Codex defaults to short MCP timeouts, while a thorough review can take several minutes. Add these values to `~/.codex/config.toml`: ```toml [mcp_servers.paranoia] command = "paranoia-local" args = ["--engine", "claude"] tool_timeout_sec = 8700 startup_timeout_sec = 60 ``` Verify the registration with `codex mcp get paranoia`. ### 4. Request your first review Ask your coding agent naturally: > Use Paranoia to critique this branch against `main`. The change is intended > to add overdraft protection to `withdraw()`. This is an internal API with > authenticated first-party callers and no hostile local processes. Use round 1. The corresponding MCP call is: ```json { "name": "critique_branch", "arguments": { "repo_path": "/absolute/path/to/project", "base_ref": "main", "round": 1, "diff_intent": "Add overdraft protection to withdraw().", "stakes": "Internal API; authenticated first-party callers; no hostile local processes." } } ``` Paranoia returns cited findings, severity tags, a reusable `session_ref`, and a computed `CONVERGENCE` result. Fix the blocking findings, increment `round`, and run the review again until the result is `CONVERGENCE: NOT-BLOCKED`. ## Choose a tool | Tool | Use it when | |---|---| | [`critique_branch`](docs/tool-reference.md#critique_branch) | You want a full review of committed or uncommitted code | | [`critique_plan`](docs/tool-reference.md#critique_plan) | You want a plan checked against the repository and its external premises | | [`query`](docs/tool-reference.md#query) | You need one cited answer, not a full review | | [`rebut`](docs/tool-reference.md#rebut) | You have evidence that a previous finding is wrong | | [`arbitrate`](docs/tool-reference.md#arbitrate) | You need Codex and Claude to decide independently between 2–4 options | The [complete tool reference](docs/tool-reference.md) documents every argument, default, constraint, result, and failure mode. ## Common workflows ### Review a branch or working tree `critique_branch` reviews `base_ref..head_ref` in an isolated temporary worktree by default. To review local edits instead, pass `include_uncommitted: true`; that mode necessarily reads the live working tree, but the reviewer remains read-only. Useful inputs are: - `diff_intent`: what the change is supposed to accomplish; - `project_summary`: neutral project context; - `stakes`: the actual deployment, trust, scale, and failure consequences; - `focus`: an optional narrow concern; and - `already_raised`: short, accepted, `file:line`-cited claims from earlier rounds. You can bind an approved implementation plan to the branch review with `plan_text` or an absolute `plan_path`. The first plan-bearing round freezes that contract for the lineage; later rounds verify the implementation against the same text. Changing the contract requires a new lineage. By default (`propose_patch` omitted), the source reviewer is asked for a supplemental unapplied candidate diff after a blocked census (the successful census lane author) or a blocked cold final (that final's own session) has settled, using that review's model and effort. Clean results report `NOT-NEEDED`; correction rounds, dirty, one-shot and closure-disabled reviews report an inert `UNAVAILABLE` and make no proposal call. `false` makes zero proposal calls; explicit `true` still rejects unsupported modes. The proposal is read-only, bound to the reviewed snapshot and complete target/class context, locally validated against pinned source, separately audited, and never applied or tested by Paranoia. The original verdict, durable state, and convergence trailer remain authoritative. A dirty caller tree blocks branch proposal spend; later ref or preimage movement marks a returned candidate stale. Clean expanded Git LFS files are recognized by verified pointer size and SHA-256 without running repository filters. Unsupported pointers remain unavailable; proposed edits still require exact committed preimages. For executing agents: inspect and amend the candidate deliberately, run appropriate checks, and submit the changed artifact in the next round. A proposal is never proof of repair. Pass `propose_patch: false` for architectural or missing-authority findings or when you already have a complete verified repair. On the next tracked round, report what you did with a pending proposal through the optional `prior_proposal_disposition` argument: the exact `PROPOSAL-AUDIT-JSON` basename, `status` (`applied`, `partially-applied`, or `departed`), and `departed_targets` mapping each departed addressed target to a one-line reason. Omission is allowed and reports `PROPOSAL-DISPOSITION: none-recorded`. Disposition is caller accounting: it never enters reviewer prompts or clearance and does not establish that a repair works. See the [caller contract](docs/tool-reference.md#proposal-disposition) and [its design record](docs/proposal-disposition-138-plan.md); Git LFS handling is specified in [the LFS cleanliness contract](docs/lfs-proposal-cleanliness-139-plan.md). ### Review a plan Tracked plan reviews require an explicit, stable lineage because plans do not have a branch name that can identify their history. ```json { "name": "critique_plan", "arguments": { "repo_path": "/absolute/path/to/project", "plan_path": "/absolute/path/to/project/docs/overdraft-plan.md", "lineage": "payments-42-plan", "round": 1, "stakes": "Internal API; one service team; about 1,000 requests/minute." } } ``` The reviewer reads the repository to test the plan's claims about current behavior. By default, it also verifies load-bearing external facts, requirements, and dependency behavior. Search discovers candidate URLs; Paranoia downloads the pages, extracts the text, binds exact passages, and uses a separate cold check for authority and entailment. Search summaries, snippets, and user-generated content cannot close a claim. Set `claim_verification: false` only when you deliberately want a structural-only review. See [external claim verification](docs/how-it-works.md#external-claim-verification) for the evidence model and limits. Plan proposals use plan-artifact.md as a virtual diff label and bind the exact captured plan bytes. The handoff identifies whether the source was plan_text or plan_path and where a path-backed plan came from. Evidence capture, binding, or cold-attestation failures remain evidence-work debt; Paranoia will not turn those operational failures into suggested factual rewrites. ### Ask a focused question Use `query` for a fast second opinion: ```json { "name": "query", "arguments": { "question": "Can this retry loop duplicate a payment?", "repo_path": "/absolute/path/to/project", "files": [{"path": "src/payments/retry.py", "reason": "retry owner"}] } } ``` It returns a direct, cited answer with a confidence level and does not create a tracked review. ### Challenge a finding Every review returns a `session_ref`. Pass it to `rebut` with concrete counter-evidence: ```json { "name": "rebut", "arguments": { "repo_path": "/absolute/path/to/project", "session_ref": "<session_ref from the review>", "rebuttal": "The call is guarded by the transaction opened at db.py:74." } } ``` The same reviewer session responds `CONCEDE` or `HOLD` with fresh citations. The unbound form is non-mutating. One-off debt with an empty class_ids list has no class-bound rebut authority. Dispute it with unbound rebut using session_ref and rebuttal, omitting all four binding fields. Carry the counter-evidence and any concession into the next critique correction's focus; debt stays open until validated settlement. Zero open classes alone never means convergence: blocking one-off debt still gates the governing CONVERGENCE verdict. For a persistently gated class, optional `lineage`, `class_id`, `debt_id`, and `lineage_mode` arguments bind the result to one current durable target. `HOLD` is audit-only. A validated `CONCEDE` closes that debt and closes its class only when no sibling blocker remains; it never grants clearance, and the next critique still performs the normal final. The closed debt retains a durable concession record. Later staged reviewers see that exact prior adjudication and must provide a keyed challenge with new resolved evidence before the same class can be violated, reopened, or replaced. The record survives unrelated snapshot and stakes changes, but it is not an exemption from a genuine changed occurrence. Bound citations use the staged anchor grammar and must resolve before settlement; tracked plan reviews retain their line count so repeated `plan:` anchors remain bounded. When a staged plan citation fails resolution, the bounded same-session retry repeats the legal `plan:<line-or-range>` grammar and the current plan bound. It explicitly tells the reviewer to discard any column component rather than concatenate line and column digits; validation never guesses, clamps, drops evidence, or partially settles an unresolved citation. Mechanized branch classes remain predicate-owned and must be closed by a normal `critique_branch` sweep rather than a bound rebut. Rebut routing uses explicit server-written successful session observations in the configured and default audit directories. A known session selects its owner unless an explicitly supplied engine conflicts. Unknown ownership requires `engine`; conflicting owners always block before spend. An incomplete audit scan disables automatic routing, while an explicit engine may proceed unless a known conflict exists. Routing does not replace durable bound-rebut authority. ### Arbitrate a decision `arbitrate` runs both vendors independently over one pinned repository snapshot: ```json { "name": "arbitrate", "arguments": { "repo_path": "/absolute/path/to/project", "decision": "Choose the numeric type for the position-size threshold.", "options": [ {"id": "float", "statement": "Store the threshold as a float."}, {"id": "decimal", "statement": "Store the threshold as a Decimal."} ], "stakes": "Internal CLI; the threshold is used only in a log line.", "files": [{"path": "scripts/lib/registry.py", "reason": "current writer"}] } } ``` Put facts shared by every option in `context`. Put each option's distinct mechanism, scope, tradeoffs, and consequences in its own `statement`. Research is enabled by default; Paranoia gives both deciders the same server-captured evidence with live browsing disabled. Python computes the outcome rather than asking a third model to choose between the votes. `arbitrate` is the only tool that consumes both subscriptions in one call. Read its [full reference](docs/tool-reference.md#arbitrate) before relying on the outcome or using `retain_snapshot`. ## Tracked reviews Tracking is on by default for branch and plan reviews. A tracked review has three phases: 1. **Census:** three cold review lanes inspect the complete artifact, followed by model consolidation. See the [census execution architecture](docs/census-execution.md). 2. **Correction:** later rounds target durable debt and the effects of your fixes. 3. **Final:** after debt closes, one fresh whole-artifact regression is required. A clean census also advances to a final rather than clearing directly. Model routing (`review_model_policy`, default `tiered`): census lanes, consolidation and the cold final use the engine's strongest model (`gpt-6-astra` / `claude-fable-5-1`, medium effort); targeted correction uses `gpt-6.1-sol` / `claude-opus-5-5` at high effort. `strongest` uses the strongest model for every structural phase. Tiered Codex routing needs a Codex CLI/account that offers `gpt-6.1-sol`: on a ChatGPT account, Codex CLI 0.156.1 rejected it as unsupported (2026-09-29) and 0.159.3 accepted it (2026-10-02), so use 0.159.3 or later. An unsupported model fails visibly rather than substituting a model: update the CLI or pass `review_model_policy: "strongest"`. Set effort per model family with `effort_by_model` (argument or a `.paranoia.toml` `[effort_by_model]` table, merged per family); a family entry beats the global `effort`, so `{"sol": "high", "opus": "high"}` keeps correction at high. The model is chosen from the authoritative durable phase, never from round labels. An explicit `model` (argument or `.paranoia.toml`) pins every structural phase as a custom override: it can clear, but its `BETA-ACCEPTANCE` trailer is labelled `custom-override`, and a later run without the override needs its own strongest cold final. An effort setting counts as a custom override only when it changes the cold final's release effort. Claim verification, `query`, `rebut` and `arbitrate` keep the call-level model. `NOT-BLOCKED` requires a cold-final acceptance record bound to the exact current snapshot; older `clear` state is re-verified by one final. Each staged trailer begins with `REVIEW-ROUTING` naming the actual phase, model, effort, policy and its source. The routing release identifier `tiered-review-beta-1` and the `BETA-ACCEPTANCE` field name are stable wire names retained from the original release; they do not mark the behavior as optional. The design record is [`docs/beta-tiered-review-plan.md`](docs/beta-tiered-review-plan.md). The engine that closes correction debt owns the resulting final-regression gate. A different engine may still report new debt, but its clean result cannot discharge that pending gate; the trailer names the required engine. Older unowned final state re-enters census once rather than guessing an owner. The retained 2026-08-23 persistent-correction acceptance predates final ownership and is historical evidence only; it does not certify the current final-selection or clearance route. Current owner behavior is exercised through both public handlers. A clear census proceeds to its cold final on the same snapshot. Increase `round` after you change the reviewed artifact to repair debt. After a clean census or clean correction (`FINAL-REGRESSION: required`), increment `round` and review the unchanged snapshot to run the cold final; edit only to repair debt. Failed or rejected rounds can reuse the same label; a successfully settled round requires the next label to increase. Paranoia tracks both concrete findings and reusable defect classes. Blocking classes remain open across rounds even if a reviewer forgets to mention them. Mechanized branch classes are rechecked against each snapshot. Plan classes are procedural and require explicit reviewer closure. `MINOR` and `OUT-OF-SCOPE` classes remain visible but do not block convergence. The key trailer fields are: | Field | Meaning | |---|---| | `CLASS-CLOSURE` | Open and closed reusable classes | | `STRUCTURAL-PHASE` | The next tracked phase: `census`, `correction`, `final`, or `clear` | | `STRUCTURAL-DEBT` | Remaining blocking findings | | `CLAIM-CLOSURE` | External-plan-claim status, when verification is enabled | | `REVIEW-ATTEMPTS` | Claim and structural attempts, including recovered validation retries | | `CONVERGENCE` | The single governing `BLOCKED` or `NOT-BLOCKED` result | `NOT-BLOCKED` means the tracked gates are clear under the stated stakes. It is a review result, not proof that the artifact is correct. A terminal claim-role failure renders `CLAIM-CLOSURE: AUDIT-FAILED`; claim counts are called last accepted only when a successful audit is bound to the exact same plan snapshot. Otherwise, including a first-audit failure or changed-plan structural preflight, preserved rows are omitted from current actionable packets and labeled non-adjudicated history rather than rewritten as `unverified` verdicts. Predecessor rows already rewritten by the old failure path receive the same conservative treatment. A missing correction-control row for an active class is initialized without discarding the other classes' counters; stale rows for inactive classes still fail closed. Correction batches independent occurrences of one reusable class into one governing finding with all distinct evidence anchors and an all-site remedy. Both plan and branch reviewers trace co-asserting sites, so definitions, call sites, tests, fixtures, and contract sections are repaired together. Each settlement retains one finding and outcome per class; historical debt IDs may close and a fresh occurrence may receive a new ID, while the server-owned correction gate still rejects rephrasing that leaves the class blocking. For an unmechanized class, correction and final use the durable class invariant and procedure as the search boundary rather than limiting review to the current debt or its known anchors. Every site or property category named there must be inspected and accounted for before the class can be reported satisfied; any surviving occurrences are returned together. Mechanized classes continue to use their server-run violation predicates. New class invariants follow the governing requirement within its supported domain; suggested repair syntax is not a separate blocking obligation. Equivalent compliant repairs are valid unless an explicit requirement mandates a representation. Mechanized predicates must not match such valid alternatives: use an unmechanized procedure when a line-level predicate cannot honestly express the violation. This authoring guidance does not override existing classes or their canonical closure authority. Every unmechanized class stores a closed list of stable member IDs. A satisfied census assessment, correction outcome, or final outcome must provide exactly one separately evidenced row for every server-supplied member ID; the server checks exact set equality before deriving and deduplicating the existing flat durable evidence list. Different members may share an anchor. On ordinary runtime load, a pre-inventory unmechanized class with no stored `members` field receives one deterministic `legacy-class-<sha256(class-id)>` compatibility member. That singleton preserves the historical whole-class evidence granularity; it does not pretend to recover an internal member set that was never stored. Historical artifact replay remains unmigrated. The retained text register still requires `MEMBERS` for new and replacement unmechanized classes. An otherwise standalone correction `close` must carry an authored `satisfied` class outcome and evidence; the server rejects a bare close through the existing bounded validation retry. A fresh aggregate finding closes the class's narrower prior open debt after incorporating every still-reachable predecessor occurrence, preventing duplicate blockers for one class. The correction materializer projects every independently authored current-occurrence anchor from the matching violated class outcome into its fresh aggregate finding, preserving authored order and recording the derived extension in the staged audit. The same projection runs before a non-debt-bound correction finding derives its violated outcome from `classification.assessment_evidence`. Every projected anchor still passes the normal snapshot and bounds validation; derivation cannot make an invalid citation valid. Correction settlement rejects any prospective state with more than one open debt for an active class. When a same-session validation retry succeeds, `CLASS-REGISTER` reports how many earlier payloads were discarded, states that none of their operations applied, and includes a bounded first validation diagnostic. The five-section review repeats bounded diagnostics under `Gaps`; `NONE` therefore means only that the accepted payload contained no class action, not that no earlier work was rejected. Broad plan census and final roles also inspect proactively for one normative contract stated as authoritative in multiple operative locations, even before the copies visibly disagree. They ask for one authoritative definition with references or derived projections elsewhere. This is a semantic review duty, not a repeated-token lint: examples, faithful table explanations, generated projections, and summaries that explicitly defer to the governing definition remain valid. Targeted correction does not reopen unrelated plan material for this audit. The retained real-provider acceptance in `docs/plan_restatement_acceptance_2026-09-01.json` binds the four-call broad census, the complete operative restatement cluster, the deferred-example exemption, durable settlement, and a separate targeted-correction scope control to exact prompts and source bytes. It then continues that lineage through a real cold final, where the previously out-of-scope duplicate contract is discovered and persisted. The validator replays every retained raw provider envelope through the production extractor and public `critique_plan` handler from source-derived initial lineages, and requires the returned result, replayable audit projection, and complete durable successor to match. The source inventory covers the complete executable `paranoia_local` package; raw stdout is the sole text-channel authority. Parsed response, session, usage, and failure detail are derived from it; the observed subprocess return code is retained separately and drives replay. Process stderr and local wall-clock duration are deliberately not claimed because neither can be independently reproduced from stdout. For lifecycle details, persistence controls, false-positive exemptions, and failure recovery, read [How Paranoia works](docs/how-it-works.md). ### One-shot reviews For an exploratory branch review with no durable convergence state, pass both: ```json {"class_closure": false, "converge": false} ``` For a one-shot plan review, pass `class_closure: false`; `converge` is not a plan argument. One-shot plan reviews still return structural prose and claim packets, but no computed convergence verdict. Plan-backed branch contracts are not available in one-shot mode. ## Configuration Add `.paranoia.toml` to a repository to avoid repeating branch-review defaults. Keys can be top-level or under `[paranoia]`. Precedence is call argument, then repository configuration, then built-in default. ```toml project_summary = "A Python booking API backed by Postgres." base_ref = "develop" stakes = "Internal service; authenticated callers; one team; about 1,000 requests/minute." web_search = true isolate = true ``` Supported keys are `base_ref`, `project_summary`, `stakes`, `isolate`, `converge`, `class_closure`, `max_packet_chars`, `model`, `effort`, `review_model_policy`, `effort_by_model` (a table), and `web_search`. For `critique_plan`, `lineage` and `class_closure` are call-only arguments and are never read from `.paranoia.toml`. The executable accepts: ```text paranoia-local --engine {codex|claude} [--log-dir DIR] ``` Audit records default to `~/.paranoia/logs/`. Durable review state defaults to `~/.paranoia/lineages/` and deliberately does not follow `--log-dir`. Set `PARANOIA_STATE_ROOT` to relocate lineage state. ## Safety and cost - Reviewers are read-only. The calling coding agent owns all edits and test runs. - Committed branch reviews use temporary worktrees; dirty reviews read the live working tree without writing to it. - Verified plans and arbitration use inert repository materializations that do not execute repository hooks, filters, helpers, symlinks, or executables. - Reviewer subprocesses ignore user tool configuration and receive only the capabilities required for their role. - Paranoia uses the CLI subscriptions you are already signed into. It needs no API keys and sends no Paranoia telemetry. - Tracked census reviews use multiple model calls. `query` is the lower-cost choice for a single question; `arbitrate` is the most expensive tool. - `arbitrate` normally creates no durable Git ref. Opting into `retain_snapshot: true` creates `refs/paranoia/arbitrate/<stamp>` until you delete it with `git update-ref -d <ref>`. Read the complete [safety, evidence, state, and rate-limit model](docs/how-it-works.md). ## Troubleshooting **The MCP call times out in Codex.** Set `tool_timeout_sec = 8700` in the MCP configuration shown in the quickstart. **The reviewer executable is unavailable or too old.** Run `codex --version` or `claude --version`, update the CLI, and confirm it is signed in in the same environment that launches the MCP server. **A tracked plan call rejects `lineage`.** Use a globally unique, mode-qualified key such as `myproject-42-plan`. Do not reuse a branch lineage for a plan. **A continuing review reports `STATE-UNAVAILABLE`.** Follow the absolute state path in the diagnostic. Repair or deliberately remove that lineage before starting again; audit logs are not backup authority for convergence state. **You only need a quick opinion.** Use `query`, or deliberately select the one-shot settings described above. ## Documentation - [Complete MCP tool reference](docs/tool-reference.md) - [Review lifecycle, evidence, safety, state, and limits](docs/how-it-works.md) - [Dense LLM/agent operating reference](docs/llm-reference.md) - [Standard LLM documentation index](llms.txt) - [Claim-verification design and acceptance notes](docs/claim_verification.md) - [Arbitration design](docs/arbitration_plan.md) - [Developer and acceptance documentation](docs/) ## Development The proposed architecture/performance work is specified in [the implementation plan](docs/review-architecture-performance-plan.md). Its acceptance distinguishes deterministic avoided calls and bounded teardown from provider-quality claims; it does not promise faster or more accurate reviews on every repository. Existing review guarantees remain in force during this work. ```bash pip install -e '.[dev]' python -m pytest python scripts/run_staged_protocol_mutation_checks.py ``` Tests use dependency-injected fake CLIs and do not consume subscription quota. The [`docs/`](docs/) directory contains design records and signed-in acceptance artifacts for provider-sensitive paths. ## Help and maintenance Paranoia Local is maintained by Andrew Hillel. Open a GitHub issue with a minimal reproduction, the tool name, bounded error text, and relevant CLI versions. Do not publish secrets or a complete private audit log. ## License MIT © 2026 Andrew Hillel