Amicus MCP server

Amicus

A multi-model LLM Council for Claude — with a parallel AI window underneath.

Hand Claude a plan, a design, a diff, an architecture decision, a manuscript — anything — and say council review this: Amicus routes it through several models from different families, has them anonymously cross-review each other, and a non-Claude chair synthesizes a verdict you turn into accept/deny edits. Or skip the ceremony and fork a single conversation to Gemini, GPT, DeepSeek, or any other model — it works in parallel with full context, and you fold the result back when you're ready. Claude orchestrates throughout; you stay in your editor.

The same council — more ways to run it: take it headless in CI with no Claude runtime, sharpen it with a debate round, or run it on free local models (Ollama, LM Studio, vLLM) at $0 — private and offline.

Quick start ↓ · Commands · Documentation · Troubleshooting

Supported clients: Claude Code CLI, Claude Desktop, and Claude Cowork are fully tested and supported. Claude Code web is experimental.

---

Table of Contents

• What is Amicus
• The Council
• Ways to run the council
• Quick start
  • 1. Install
  • 2. Configure — don't skip this
  • 3. Your first council
  • 4. Your first sidecar
• Requirements & Dependencies
• The parallel window
• Commands
• Models
• MCP integration
• Configuration
• JSON output
• Windows
• Troubleshooting
• Documentation
• Contributing
• Built on OpenCode
• Attribution & License

---

What is Amicus

One install delivers six things that work together:

• The second-opinion LLM Council skill. Structured multi-model review: independent reviews → anonymized peer cross-review → a non-Claude chair verdict → tiered accept/deny decisions. This is the hero.
• The sidecar chat skill. Ad-hoc fork/work/fold — spin up one other model in a real window (or headless), work alongside it, fold the summary back.
• The amicus CLI (with an am alias) and an MCP server. The engine underneath both skills: launches sessions, shares context, runs parallel waves, and exposes the same surface to Claude as MCP tools.
• A self-updating model catalog. Aliases and validation resolve against a live catalog fetched from provider APIs (cached locally), so model names stay current without a hard-coded table.
• Observability. amicus watch <id> renders any live or finished run (fan-out or council) from any terminal; --follow streams milestones as they happen; --on-complete fires a hook when a run lands; --retry-failed plus opt-in cheaper-model fallbacks recover dead legs without relaunching the whole wave; amicus spend answers "what did this cost, and where" with per-run attribution.
• Council Workspace. amicus watch <runId> --ui: a window that shows a council thinking — live seats, the anonymized judge packet, the adjudication matrix, dissent drill-in, chair verdict, and cost-by-seat — for both live and historical runs. It also auto-opens on an MCP-invoked council run from Claude Code (local), so you no longer have to remember the flag (see docs/council.md).

Claude is the orchestrator. The council and chat skills run on top of the engine; you talk to Claude, and Claude drives Amicus.

---

The Council

Trigger it by saying "council review this" to Claude, or, on the plugin channel, run /amicus:council directly.

Why multi-model. Any single model — including the one running your session — has consistent blind spots. Route the same material through models from different families and the disagreements surface: missed issues, overstated confidence, claims one model alone would have waved through. The council is the structured version of that idea.

The flow, in five beats:

1. Independent reviews. Each council model reviews the artifact on its own (one parallel wave), producing a structured findings list — claim, severity (blocker | major | minor | nit), location, rationale.
2. Anonymized cross-review. Claude relabels every review (Review A, B, C…) and sends the identical bundle to every model. Each model ranks the reviews and adjudicates every finding (agree | dispute | neutral) — unknowingly judging its own, so self-bias washes out. This yields a street-cred ranking and sorts findings into Disputed / Confirmed / Contested / Singleton tiers. Self-bias is washed out per seat: if you deliberately seat one model twice, each seat's vote on the other seat's finding is counted as the real peer vote it is, and the finding is flagged when its only corroboration came from its own twin.
3. Chair verdict. A designated non-Claude chair receives the de-anonymized picture — all reviews, rankings, and adjudications — and synthesizes an independent verdict. Claude presents it verbatim; Claude does not synthesize.
4. Tiered decisions. Confirmed findings get one bulk accept/deny; Contested and Singleton findings are decided one at a time (accept / deny / modify).
5. Outputs applied. Accepted findings are written into a reviewed copy of the source; the full run is captured in the run folder.

flowchart LR
    A["Artifact"] --> B["Independent<br/>reviews"]
    B --> C["Anonymized<br/>cross-review"]
    C --> D["Chair verdict<br/>(non-Claude)"]
    D --> E["Tiered<br/>accept / deny"]
    E --> F["Reviewed copy<br/>+ run folder"]

What a run produces (in output/<stem>-council/):

• review-<model>.md × N — each model's independent review.
• crossreview-matrix.md — the adjudication grid plus the de-anonymized street-cred table.
• verdict.md — the chair's synthesis.
• report.md — synthesis + the full decision log + a per-call run-stats table.
• report.html — the deterministic renderer output (adjudication matrix, street-cred table, findings-by-tier, cost — no chair prose). This is the default artifact handed to the user.
• For an editable source, the accepted edits land in <stem>-reviewed.<ext> next to the original.

Optional council elements (v2.2.0, all default off): four opt-in behaviors, offered once as a menu at launch — nothing turns on unless you name it, and the confirmation lists exactly what's on. Chair verdict scale (standard since v2.2.0's follow-ups — no longer opt-in): the chair always closes with 3–5 hard questions and one parseable VERDICT: Ship it | Fix these first | Fundamental rethink line.

• Critic seat — one reviewer swaps to a four-pass adversarial brief (adversarial pass, edge-case hunt, consistency check, executability test). Its findings enter the same anonymized bundle as everyone else's, so the bench disciplines the critic: manufactured negativity lands Disputed and dies in the tally.
• Expert lenses — each reviewer takes a distinct expert perspective; you pick the panel domain (business, technical, customer, financial, or custom). Lens runs never feed the reliability ledger, and the report discloses the weakened cross-review anonymity.
• Debate mode — after cross-review, every Contested or Disputed finding goes back to its raiser to defend, amend, or withdraw, and the disputing judges re-vote. Exactly one rebuttal round, then the final tally.
• Claude in the council — Claude adds its own fresh review to the bundle so the bench ranks and adjudicates it. Claude is judged but never votes or chairs, so the verdict stays independent.

The critic and lens methodologies are adapted from the /critic and /debate agents in John Renaldi's product-kit (MIT); the briefing boilerplate lives in skills/second-opinion/SEAT-BRIEFS.md.

Cost is disclosed up front. Before any model launches, you see the run shape — including any enabled optional elements — for example:

This run uses 3 council models across 2 fanout waves + 1 chair call, with critic seat + debate mode ON (~7 base runs + up to 6 rebuttal calls).

Then the council waits for your confirmation.

The skill lives at skills/second-opinion/SKILL.md; the design spec behind it is skills/second-opinion/COUNCIL-DESIGN.md. For what amicus council tally|verdict|report|stats actually take as input and produce — field-by-field schemas, verdict.json's provenance, and a full worked example run against the real CLI — see docs/council.md.

---

Ways to run the council

The council is the hero — start with the everyday way, and reach for the more powerful ways when you need them:

• Just ask, in Claude Code. Hand Claude a plan, diff, design, or manuscript and say "council review this." The second-opinion skill runs the whole ritual above in your session, with no setup beyond your API keys. This is how most people use it. → Quick start
• Headless, in CI, with no Claude runtime. amicus council run --prompt-file plan.md --council free runs that same pipeline in one command — reviews → cross-review → tally → chair verdict — writing verdict.json and report.html. It needs no Claude session, so it drops straight into CI. → Headless council (CI)
• With a debate round. Add --debate and every Contested or Disputed finding goes back to its raiser to defend, amend, or withdraw while the disputing judges re-vote — exactly one rebuttal round, then the final tally. → The Council
• On free, local, private models — at $0. Point the council (and sidecars) at an OpenAI-compatible server already running on your machine — Ollama, LM Studio, or vLLM — with amicus provider add. No API key, no per-token bill, nothing leaves your machine, and it works offline. → amicus provider
• Pointed at the work itself, not at a review of it. Add --intent task and the same bench produces the deliverable instead of critiquing one. → Task mode (v4.9)

Headless council (CI)

The same pipeline runs with no Claude runtime at all: amicus council run --prompt-file briefing.md --models gemini,glm --chair deepseek --json executes the review waves, the anonymized cross-review, the tally, and the chair verdict in one command, and writes the full run directory (verdict.json with the chair's parsed overallVerdict, report.html, every review and judge output). That is what powers the repo's own Council Review GitHub Action v2 — on PRs labeled council-review it posts an adjudicated verdict as a check run plus a sticky comment, uploads the run directory as an evidence artifact, and gates merges by default via its fail_on input (fails only on a Fundamental rethink verdict; pass fail_on: fix to require Ship it, or fail_on: none for report-only). Reference: docs/council.md.

That action can pin a seat's OpenRouter upstream — and ships with no pin in force (#202). OpenRouter serves one model from several upstream providers, and nothing a run records says which one served a leg, so a slow upstream is indistinguishable from a slow model. Setting the workflow's COUNCIL_PROVIDER_ROUTING to a routing document makes it write an opencode.json into the run directory before the paid step, pinning one bench model's upstream (provider.openrouter.models.<id>.options.provider); with a single-slug only that model's legs become attributable by construction. It ships blank. The #202 Lever 2 experiment ran two live rounds with qwen pinned to one upstream and the time-to-first-token tail did not move: in both rounds the pinned seat's first attempt died at the no-output backstop, round 1's retry died too (912 s) and lost the seat, and only in round 2 did the retry — and its judge leg — complete through that same upstream (3 of the 5 pinned legs across the two rounds failed). So a pin is not a fix, and a merge-gating seat does not sit on a single upstream for no measured benefit. The machinery stays, gated and tested, for the next question. When a pin is set: the document is validated before it is written, a keyless pre-run check skips the pin for that run if a named upstream is not listed and serving, a keyless canary pins that the engine still carries the file to the request body, and a post-run step warns when a pinned model's leg died. To read such a run, open its council-run evidence artifact — the opencode.json inside it is the routing that was in force.

Free council (zero-cost)

Want the cross-examination without the model spend? amicus setup offers a Free OpenRouter council mode — readline wizard option 2, and the Electron Models step. It detects the free :free models live from the catalog, lets you multi-pick (Enter takes a vendor-diverse default), and saves them as councils.free — a first-class councils config primitive seeded under collision-safe free-* aliases. Your config.default is left untouched, and all you need is an OPENROUTER_API_KEY.

Run it anywhere a council runs:

amicus fanout --council free --prompt "Review this design"

The amicus_fanout MCP tool takes the same council parameter, and the second-opinion skill reads councils.free automatically. A member that gets delisted is dropped with a warning — the council still runs as long as ≥2 survive. Free models are rate-limited and quality-variable, and some return 404 unless you enable data-sharing at openrouter.ai/settings/privacy.

Council presets

Save your own named member lists with amicus council save <name> --models a,b,c (≥2 resolvable aliases or provider/model IDs), then run them with --council <name> anywhere a council runs. amicus council list shows saved presets plus three built-in benches that work with no setup at all — free (the same zero-cost dynamic pick described above, used when you haven't seeded councils.free), budget (cheap workhorses, one per vendor family), and frontier (premium flagships, one per vendor family). amicus council show <name> resolves any of them (saved or built-in) and reports which members are currently usable. A saved council always shadows a built-in of the same name — exactly how the wizard's councils.free seeding already worked.

Policy packs (v4.5)

A council preset only saves the bench. A pack saves the whole run — bench, chair, critic/lenses, cost/timeout options, and a briefing template — as one named, shareable JSON file:

amicus pack save review-bench --kind council --bench gemini,deepseek,gpt --chair opus --timeout 20 --max-cost 2
amicus council run --pack review-bench --prompt-file plan.md --json

Any flag you also type on that second line overrides just that value — a pack only fills in what you didn't say explicitly, and it's recorded on the run either way. Packs work the same way on fanout/start and on the amicus_fanout/amicus_start/amicus_council_run MCP tools. amicus pack list/show/rm manage them, and --from-run <id> builds one from a run you already liked instead of typing flags at all. Full reference: docs/usage.md § Policy packs.

Task mode (v4.9)

A council reviews by default. amicus council run --intent task --prompt-file brief.md — or intent: 'task' on the amicus_council_run MCP tool — points the same pipeline at open-ended work instead: every seat produces the analysis, answer, or artifact the briefing asks for, the judges rank which response best does the work and adjudicate the claims each one declared, and the chair synthesizes an answer — Converged | Split | Insufficient — never a review verdict. The two scales share no value, so a task run can never report Ship it and a review run can never report Converged. Task runs deliberately write nothing to the reliability ledger (rankings there measure concurrence, not defect confirmation) and say so on the surfaces that would otherwise look empty; a review run is byte-identical to before. Full reference: docs/council.md § Task mode.

Briefing templates (v4.5)

--template <name> --artifact <file> (plus repeatable --var k=v) renders a {{prompt}}/{{artifact}}-style Markdown template before it's sent, on start/fanout/council run alike — templates live in ~/.config/amicus/templates/, and a pack's briefing.template is how one reaches an MCP-invoked run (MCP has no template param of its own). amicus template list|show manage them; v4.5 ships one built-in, review. Full reference: docs/usage.md § Briefing templates.

---

Quick start

Two install channels — read this first. Amicus ships two ways, and CLI commands look different in each:

• npm global (npm install -g amicus or the install script) — the recommended path. Puts amicus/am on your PATH, so every amicus <command> example in this README works as written, and provisions the Electron GUI that the parallel window runs in.
• Claude Code plugin (/plugin install amicus@bourbondog-amicus) does not put a CLI on your PATH. CLI calls go through npx -y amicus@latest <command> instead — e.g. amicus doctor becomes npx -y amicus@latest doctor. In exchange, the plugin channel gets two things npm does not: the slash commands /amicus:council and /amicus:sidecar. These are plugin-channel-ONLY — npm users don't get them and drive the same skills by saying "council review this" / talking to Claude instead.

See the comparison table below for the full tradeoff — the short version is that npm is what you want for the interactive window, and the two can be installed side by side.

Convention used throughout this README: plugin-channel users: prefix CLI examples with npx -y amicus@latest (skip the bare amicus/am). Individual code blocks are not duplicated per channel — this note is the one translation you need.

1. Install

Every path delivers the MCP server and both skills. They differ in what else you get:

	npm / install script	Claude Code plugin
amicus / am on your PATH	✅	❌ — every call is npx -y amicus@latest <command>
Interactive Electron window (amicus start, watch --ui)	✅ provisioned at install	⚠️ best-effort — see below
Self-heal when the GUI breaks (amicus doctor --fix)	✅	❌ no CLI to run it with
MCP server + both skills	✅	✅
Slash commands /amicus:council, /amicus:sidecar	❌	✅

---

With npm — recommended

The canonical path, and the one that gets you the full interactive experience (needs Node.js ≥ 22.12):

npm install -g amicus

This is the path to pick unless you specifically want the plugin's slash commands. It puts amicus/am on your PATH — which is what the parallel window is driven by — and its postinstall provisions the Electron GUI, with amicus doctor --fix to repair it in place if anything goes wrong later.

With the install script

Same result as npm, one command — macOS, Linux, or Windows (needs Node.js ≥ 22.12):

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/BourbonDog/amicus/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/BourbonDog/amicus/main/install.ps1 | iex