Adversarial Friends

Hand your spec, plan, or review to agent CLIs — claude, codex, Antigravity (agy), opencode — under adversarial lenses, then merge their critiques into one ranked findings report.

It automates a workflow you may already do by hand: run a review, paste the findings into a different model, ask whether they hold up, carry the argument back. Doing that manually means holding a claim ledger in your head. This keeps the ledger on disk.

📋 Contents

• Why more than one model
• Install
• Quickstart
• How it works
• Lenses
• What you get back
• What's implemented
• Documentation
• Development

🎯 Why more than one model

A single reviewer produces confident prose. Several reviewers produce claims that can be compared — and the disagreements are where the real problems are.

This tool's own design spec was built exactly this way:

That unproven claim was later confirmed and fixed. No single reviewer's pass would have surfaced all of it — see the revision history in the design spec for the full account.

📦 Install

Requires Python 3.11+ and at least one agent CLI. Judging modes additionally require two independent non-host friends. The runner itself is stdlib-only — zero runtime dependencies.

uv tool install adversarial-friends

# From git, for a version that is not yet released
uv tool install git+https://github.com/livingstaccato/adversarial-friends

# From a local checkout
git clone https://github.com/livingstaccato/adversarial-friends
cd adversarial-friends
uv tool install .

# Without installing at all
python -m adversarial_friends doctor

Then confirm what's actually available:

afriend doctor

doctor reports shared readiness — including ready, reachable-unconfigured, unavailable, disabled, host-excluded, and policy-blocked — plus what each friend can genuinely enforce. For Ollama, reachability alone is insufficient because dispatch also requires a model.

🚀 Quickstart

In an agent host, select /afriend to route an explicit Adversarial Friends request, or select $adversarial-friends:afriend directly. It hands review, status, setup/configuration, and resolution requests to focused skills: review, status, configure, and resolve.

Conversational phrases such as afriend review and afriend status are routing language, not executable aliases: the stable CLI commands remain afriend run, afriend status, and afriend doctor. afriend resume <run-id> similarly routes to afriend run --resume <run-id>; it is not a claim resolution and needs no disposition or evidence.

afriend run docs/my-design.md

On the first review request in a host task, /afriend presents one compact preflight before dispatch:

About to start Adversarial Friends to review <artifact> in <mode> mode with <profile>. Scope: <repository snapshot|document only>. Friends: <name, provider, lens, role>; external tools: <denied|explicit grant>.

You can accept it, choose a task-only profile or mode, change the task-only roster, or stop. It is shown again only before a requested new loop iteration. The preflight describes authority; it never grants external tools, provider enablement, unsafe arguments, or sandbox exceptions. Direct CLI runs stay non-interactive.

The built-in profiles are quick (one report fan-out), balanced (crossexam), and thorough (loop). quick is the default. Use --profile NAME for one run; an explicit --mode wins over the profile's mode and other explicit safe run flags win over profile values.

The host is the orchestrator. In Codex, Codex remains the orchestrator and is included as a friend by default. The report labels it host-self-review (advisory), independent=false: it contributes findings and advisory verdicts, but cannot satisfy two-independent-friend admission, --require-friends participation, judging quorum, gate clearance, or loop convergence. Judging modes need two independent non-host friends in addition to any host; a report can be host-only. Non-Codex hosts are excluded by default. --include-self and --exclude-self are mutually exclusive overrides.

Manage persistent user defaults, including a default Ollama model, with:

afriend providers list
afriend providers enable claude
afriend providers disable opencode
afriend providers set-model ollama qwen3:8b
afriend providers clear-model ollama

Set up those defaults with an inspectable no-write preview, then apply only the exact choices you name:

afriend init --guided
afriend init --guided --default-profile balanced --enable-provider claude
afriend init --guided --apply --default-profile balanced --enable-provider claude

Guided setup reports discovered providers, the Codex advisory-host role when applicable, built-in profiles, and that external tools remain denied. Plain afriend init remains the direct roster-generation command.

Manage named user profiles separately:

afriend profiles list
afriend profiles create focused --base quick --timeout 300
afriend profiles set-default focused

Profiles can carry only review-safe mode, preset, lenses, friend/timeout ceilings, and round/iteration ceilings. They cannot select providers, a friend roster, models, credentials, forwarded environment, external tools, unsafe arguments, or sandbox exceptions.

For one automatic roster, --enable-provider NAME and --disable-provider NAME override those defaults. Disabled providers are not probed. An explicit --friend roster remains authoritative and may name the host or a disabled provider.

External-tool authority is separate from provider selection. The repeatable required-value form is --allow-external-tools=PROVIDER; the explicit global grant is --allow-external-tools=*. Unknown, duplicate, or mixed * plus provider grants are invalid, and the old valueless form is invalid. --unsafe-extra-args requires the global * grant plus --i-accept-unsandboxed. Grants do not change provider defaults and must be repeated as the same normalized set on resume.

Stdout carries one thing — the run directory. Read report.md inside it:

cat "$(afriend run docs/my-design.md --mode report)/report.md"

Pick your reviewers and lenses explicitly:

afriend run spec.md --friend codex:security --friend claude:ops

A third slot picks the model — required for ollama, which has no default:

afriend run spec.md --friend ollama:security:qwen3:0.6b

⚠️ --friend replaces discovery rather than adding to it. One --friend flag means a one-friend roster. A report with one friend is allowed as a recorded downgrade in run.json and report.md rather than being presented as a full review. crossexam, gate, and loop require at least two independent non-host friends; with fewer, they refuse with exit 3 before a run directory is created.

Runtime depends on the slowest selected friend, document size, and mode. Progress goes to stderr: a line per friend as it finishes, and a heartbeat naming whatever is still outstanding, so a quiet run is distinguishable from a hung one. --no-progress silences it for a caller that captures both streams together; reducing --timeout turns slow friends into failures rather than making them faster.

Each run also appends safe lifecycle records to events.jsonl: run_started, friend completion/failure, round completion, and run_finished. Records carry only identity, mode/profile, scope, status, round, duration, and next action; they never copy prompts, raw outputs, diagnostics, credentials, environment, or authority grants. After the run, inspect it without dispatching anything:

afriend status <run-id-or-path>
afriend status <run-id-or-path> --watch
afriend status <run-id-or-path> --json

--watch prints only new lifecycle events until the terminal event and treats an unterminated final event line as still being written. Runs without an event stream remain inspectable from run.json, claims.jsonl, and report.md.

⚙️ How it works

Every friend gets its own prompt built from its own lens, runs in its own isolated directory, in its own process group:

The snapshot includes untracked files (git stash create omits them), and the working tree is never touched — a friend reviewing your repo can't see a half-staged index or scribble on your checkout.

There are two supported ways to select review context:

afriend run docs/plan.md --mode report
afriend run /tmp/reviews/plan.md --repo "$PWD" --mode report

The first form selects scope automatically only when the artifact's resolved final target is inside the invocation repository: it receives a repository snapshot. An in-repository symlink whose target resolves outside that repository is doc scope only, and no repository snapshot is minted; a path outside a Git repository likewise produces a visible doc-scope warning on stderr before friends start. The second form selects the named repository explicitly; --repo must name that repository's Git worktree root. It is the deliberate route for an independently frozen external artifact together with selected repository code. It does not grant new provider, external-tool, or write authority. Normal untracked, non-ignored files are included in an automatic snapshot.

Gitignored artifacts are intentionally excluded from automatic Git-blob binding and fail rather than falling back to a stale HEAD version. Use the explicit --repo form when an ignored or outside artifact needs the named repository's code context.

On Linux, a confined friend uses bwrap with the required system paths read-only. If /etc/resolv.conf resolves to a safe regular file elsewhere on the host, the sandbox exposes that resolver target read-only too. DNS therefore continues to work without granting general access to the host filesystem.

For a provider without a verified read-only/write-protection mode, make sandbox-exec (macOS) or bwrap (Linux) available, or choose a provider with a verified read-only/write-protection mode. That mode controls writes, not filesystem reads, and does not replace OS read confinement. A provider with a verified read-only/write-protection mode does not need --allow-unsandboxed-friend. That flag is explicit risk acceptance, not a normal fix: the affected provider runs without OS confinement and retains same-user filesystem read access.

Corroboration is the point

Two friends independently reaching the same conclusion is the strongest signal this tool produces, so deduplication is built to never destroy it:

Dedup is deliberately exact-match — whitespace and case only. Two friends describing one defect in different words produce two claims, which costs a round. Guessing at equivalence would corrupt the ledger, which is worse.

Claim states in cross-examination

Every claim --mode crossexam produces ends in one of eight states. Two of them — deadlocked and settled-upheld — deliberately need a human, and the report says so rather than quietly resolving them.

The gate loop

--mode gate is the one that fails a build, and clearing it is a back-and-forth rather than a single command:

🔬 Lenses

A lens is prose, not a config string. Its text is injected into that friend's prompt, so it shapes what the friend actually looks for.

scope is the one lens that doesn't demand a concrete failure scenario; "this is more than you need" is a legitimate finding without one. Claims from it are marked (advisory) in the report so they never carry the same weight as a reproducible defect.

📂 What you get back

<run-dir>/
├── report.md          ← ranked findings, corroboration, downgrades
├── run.json           ← machine-readable: friends, statuses, downgrades
├── events.jsonl       ← append-only safe lifecycle events
├── claims.jsonl       ← append-only ledger: claims, aliases
├── artifact/          ← frozen copy of what was reviewed, hashed
└── round-1/
    ├── <friend>.prompt ← exactly what this friend was asked
    ├── <friend>.raw    ← its unmodified stdout
    ├── <friend>.err    ← its stderr (always present, even when empty)
    ├── <friend>.meta   ← argv, exit code, duration, timeout, orphan status
    └── <friend>.sandbox ← the OS policy it ran under, when one was applied

Runs land under ${XDG_STATE_HOME:-~/.local/state}/adversarial-friends/runs/, or wherever --out points.

Everything a friend was asked and everything it said is on disk. When a run comes back thin, that's what you read — not a guess.

✅ What's implemented

All four modes run.

afriend run docs/design.md --mode crossexam
afriend run docs/design.md --mode gate       # exit 1 while anything blocks
afriend resolve <run-id> --list
afriend resolve <run-id> --next
afriend resolve <run-id> --claim c-0001@1 \
    --disposition fixed --evidence src/auth.py:38

Disagreement is the output rather than a problem: two judges who still disagree at --max-rounds leave the claim deadlocked, and the report quotes both sides verbatim instead of resolving it by majority.

A resolution is an attestation, and the tool says so. It cannot know a defect is gone — only whether the location you named actually changed since the run started. A fix that landed outside the reviewed artifact is fine. --disposition fixed requires a verifiably changed location; unchanged or unverifiable evidence is refused. Use accepted-risk when verification is intentionally unavailable.

Deduplication is judgment the runner declines to fake. --merge exact (the default) merges only identical claims and always finishes unaided; --merge orchestrator stops with exit 10, writes the claims to REQUEST.json, and waits for you to say which are duplicates:

afriend run docs/design.md --merge orchestrator   # exit 10, writes REQUEST.json
# ...fill in the merges, save as RESPONSE.json...
afriend run --resume <run-id>                     # round 1 is not re-run

Resume verifies the original frozen artifact hash and saved Git snapshot before dispatch; it never substitutes current files. It uses the saved repository scope and rejects --repo, so a resume cannot replace the original automatic or explicit selection. Security grants are also never restored from run.json: options such as --allow-external-tools=PROVIDER grants (or the global =* grant) must be repeated as the same normalized set.

Tired of --friend flags? afriend init writes a roster from what is actually installed, and ~/.config/adversarial-friends/roster.toml is picked up automatically. A repo-local roster never is — a cloned repo does not get to choose who reviews it (§13).

The same halt serves unparseable output (§14.2): repair is a pure transformation with no model call, so when it fails the runner asks you to read the raw text rather than discarding whatever the friend found.

There is no --max-spend-usd. A dollar cap needs per-CLI cost reporting nobody has captured, and a flag that silently never fires is worse than none — you would set it and believe you were protected. Use --max-calls, which is derived from your roster and actually enforced.

Antigravity's controlled reviewer is staged into the run's isolated workspace; it does not edit global Antigravity configuration. The staged agent and --sandbox are defense in depth, but sandbox does not mean external tools were denied. Antigravity remains external_tools=uncontrolled because its CLI cannot prove every plugin/MCP integration disabled invocation-locally. That is an accepted best-effort limitation: Antigravity is policy-blocked by default, while --allow-external-tools=agy records it as explicitly-allowed.

Antigravity is the shipped Google harness, identified as agy in CLI and provider configuration.

Exit codes

A ceiling outranks everything below it, so a CI wrapper can read 11 as "retry" and 1 as "block" without ambiguity.

📚 Documentation

Using it as a skill or plugin

The skill payload ships inside the wheel as package data, and is mirrored under plugins/ for loaders that can't install a Python package:

# Claude Code
/plugin marketplace add /path/to/adversarial-friends/plugins

Plugins package capabilities; the Adversarial Friends plugin provides exactly five skills: /afriend, review, status, configure, and resolve. /afriend is the only router and short slash selector; direct qualified selection is $adversarial-friends:afriend. The CLI never runs automatically by itself. Generic “review this,” “poke holes,” “second opinion,” and architectural decision requests stay ordinary Codex work.

The package must therefore be installed for the skill to work — afriend doctor is the check. Conversational forms route to stable commands; they are not executable aliases.

🛠 Development

make install    # uv sync
make test       # pytest
make quality    # every portable CI gate, wheel checks, and tests
make diagrams   # re-render docs/architecture/*.puml

make quality runs every portable CI gate, including wheel construction and isolated installation. Linux CI additionally installs bubblewrap and requires the real OS-confinement tests to execute; macOS cannot reproduce that Linux- specific assertion locally. Use make act-ci for the closest local Linux run.

Two gates catch drift that is otherwise silent:

• plugin-sync — src/adversarial_friends/assets/ is canonical; its entrypoints project directly to plugin skills and runtime assets project beneath skills/afriend/. Edit assets, then make plugin-sync-copy.
• version-sync — VERSION must match the version field in every plugin manifest.

See AGENTS.md for repository layout and conventions.

📄 License

MIT — see LICENSE.