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:

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

As a Claude Code plugin

The most native registration path if you use Claude Code, and the only one with slash commands:

/plugin marketplace add BourbonDog/amicus
/plugin install amicus@bourbondog-amicus
/reload-plugins

Claude Code registers the MCP server and both skills for you — nothing to configure. You also get /amicus:council (run a full council review) and /amicus:sidecar (fork a conversation to another model), which the npm paths don't have.

Know the tradeoff before you pick this. The plugin does not put amicus on your PATH, so every CLI call goes through npx -y amicus@latest <command> — including the ones that open the interactive window. It also skips amicus's postinstall, which is what provisions and self-heals the Electron GUI. The window still works when Electron lands in the npx cache, and the Council Workspace still auto-opens on a council run from Claude Code — but nothing repairs it when Electron doesn't land, and each new release re-resolves into a fresh cache directory. If you want the parallel window as a daily driver, install with npm.

(Also: the first council/sidecar call downloads the OpenCode engine.)

Running both is supported — and is what you want if you like the slash commands and the window. Install with npm for the CLI and the GUI, then add the plugin for /amicus:council. Your config, API keys, and session history live outside either install and are shared automatically.

One thing to know if you do: the MCP server is a single registration named amicus, so it resolves to one install — whichever registered most recently, which is usually the plugin's npx -y amicus@latest mcp. That's harmless (both serve the same tools), but it means the copy your CLI runs and the copy Claude's MCP tools run can differ. amicus doctor reports the MCP launch path explicitly and --fix repairs that copy in place, so if a GUI or engine problem ever shows up in Claude but not in your terminal, that's the first thing to check.

For the npm and install-script paths, a postinstall auto-configures everything — no manual registration:

• Registers the MCP server in Claude Code and in Claude Desktop / Cowork, so the Amicus tools appear natively.
• Installs both skills into ~/.claude/skills/ — second-opinion (the council) and sidecar (the chat skill).

Skipped the postinstall? --ignore-scripts npm installs never run it, and the plugin channel skips it by design (Claude Code registers the plugin's MCP server and skills itself). Either way, run amicus init (plugin channel: npx -y amicus@latest init) any time to (re)register on demand — e.g. to also wire up Claude Desktop, which the plugin path doesn't touch. See amicus init.

2. Configure — don't skip this

⚠️ Installing is not enough. Run this or nothing will work.

Amicus has no API keys of its own — it drives your accounts at OpenRouter, Google, OpenAI, Anthropic, or DeepSeek. Until you add at least one key, every council and every sidecar fails at the first model call. This is the step people skip.

amicus setup
# plugin-only install (no CLI on PATH):
npx -y amicus@latest setup

One key is enough to start. OpenRouter is the usual choice — a single key reaches every model in the catalog, which is what makes a mixed-vendor council work without four separate accounts.

This opens a graphical wizard:

Headless environments: if Electron can't open a window, the wizard falls back to a readline-based setup in the terminal.

Confirm it took — this is the fastest way to know you're actually ready:

amicus doctor

Green across the board (0 error(s)) means keys, catalog, engine, skills, and MCP registration are all in place. Anything red, amicus doctor tells you exactly what to run next.

3. Your first council

No flags to learn. In Claude Code or Cowork, give Claude a document and say:

council review this

Plugin-channel users can also type /amicus:council directly instead of phrasing it as a request — same skill, explicit invocation.

Claude prepares the material, recommends a bench of models, discloses the run shape and cost, and orchestrates the rest. You make the accept/deny calls at the end. (The second-opinion skill is what teaches Claude to recognize this — if nothing happens, run amicus doctor (or npx -y amicus@latest doctor). npm/install-script installs place the skill at ~/.claude/skills/second-opinion/; plugin installs keep it inside the plugin itself — check /plugin in Claude Code to confirm amicus is enabled.)

4. Your first sidecar

The sidecar is the lower-level path — you can invoke it by phrase through Claude too, but the CLI gives you the flags directly:

amicus start --model gemini --prompt "Fact-check the auth approach Claude just proposed"

A window opens alongside your editor with Gemini ready, pre-loaded with your conversation. Work with it, then Fold the summary back.

Updating

Amicus checks the npm registry at most once every 24 hours (cached background check). When an update exists, the CLI prints a notice and the Electron toolbar shows a one-click Update banner. Or run it yourself:

amicus update

Install from GitHub

The npm package is the primary path. To install straight from the repo instead — the postinstall runs identically (same MCP registration, same two skills) — you just need git on your PATH:

npm install -g github:BourbonDog/amicus

See Requirements & Dependencies for the full prerequisite list.

Contributor setup

Cloning to develop Amicus? See CONTRIBUTING.md for the dev setup, git-hook wiring, and test commands.

Requirements & Dependencies

Everything you need before your first run, and what's optional.

Runtime

• Node.js ≥ 22.12 — node --version to check. This is the only hard runtime prerequisite.
• An active Claude Code or Cowork session — Amicus is orchestrated by Claude; it is not a standalone chatbot.

Install path & the git toolchain

• From the npm registry (recommended): npm install -g amicus. No build toolchain required — the package ships prebuilt.
• From GitHub: npm install -g github:BourbonDog/amicus runs identically — same MCP registration, same two skills, same postinstall. The one extra requirement is a working git on your PATH, since npm clones the repo to install it (git --version to check).

Model API keys — at least one is required

• OpenRouter covers the most models with one key, or use a direct Google / OpenAI / Anthropic / DeepSeek key. Add one with amicus setup or amicus key <provider> <key>; keys live in ~/.config/amicus/.env. The supported env vars are OPENROUTER_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY (the legacy GEMINI_API_KEY is still accepted), OPENAI_API_KEY, ANTHROPIC_API_KEY, and DEEPSEEK_API_KEY.
• Or skip cloud keys entirely and run local, at $0. Point Amicus at an OpenAI-compatible server already running on your machine — LM Studio, Ollama, or vLLM — and there's no API key, no per-token bill: amicus provider add lmstudio --preset lmstudio (LM Studio), --preset ollama (Ollama), or --preset vllm (vLLM). See amicus provider.
• ⚠️ OpenRouter keys need purchased credits. A brand-new, zero-credit key passes setup's live validation but then fails at runtime with a 402 on the first real call. Buy a small amount of credit before you run a council.

Electron — optional (GUI only)

• Electron is an optional dependency. It powers the graphical setup wizard and the parallel sidecar window. Headless runs and the full council work without it — if Electron is absent or can't open a window, amicus setup falls back to a readline wizard and sidecars run headless. amicus doctor reports Electron's presence accurately and never treats its absence as fatal.

The OpenCode engine

• The bundled opencode-ai engine (the conversation runtime) installs automatically as a normal dependency — you don't install it separately. Its own postinstall lays down ~11 per-platform binaries; a transient failure there (a spawn ENOENT, or an antivirus file-lock) can roll back the atomic install. If install fails partway or amicus doctor reports the OpenCode binary "not found", just re-run npm install -g amicus (clear the cache first if it persists: npm cache clean --force).

OS support

• Windows 11, macOS, and Linux are all supported; Amicus is first-class on Windows (developed and tested there, no WSL required). See the Windows section for platform specifics.

What a run costs. A sidecar is a single model call. A full council is typically ~5–8 paid model calls (e.g. 3 reviewers across 2 fan-out waves + 1 chair). Amicus shows an estimate before each council and enforces a built-in budget gate that refuses ultra-expensive models (o3-pro class) unless you opt in with --no-cost-gate. You pay your providers directly for the tokens; Amicus itself is free and open-source.

The parallel window

When you don't need a full council — just one other model's take — fork a conversation. Amicus extracts your current Claude Code context, opens a session pre-loaded with it, you work alongside it, and you fold a structured summary back into Claude's context when you're done.

Interactive (default): a real window opens next to your editor. Switch models mid-conversation with the model switcher, then click the FOLD button (or press Cmd+Shift+F) to generate the summary. Customize the shortcut with --fold-shortcut.

Headless (--no-ui): the agent works autonomously and emits the fold summary when it finishes — ideal for bulk work like test generation or documentation. Pair with --json for a machine-readable run document.

How the fold handoff actually works. A fold is a summary handoff, not a live handback — once you fold, the sidecar model's context is gone. Mechanically: clicking FOLD asks the model for a structured summary, then writes it to the Electron process's stdout as a [SIDECAR_FOLD]-tagged block; the amicus runner that spawned Electron captures that stdout and persists it as the session's summary.md (under the session directory, alongside metadata.json and conversation.jsonl). Nothing pushes the result back to you automatically — your orchestrating agent picks it up on request, via amicus read <taskId> (CLI) or the amicus_read MCP tool. Either path returns the summary wrapped in an <untrusted_sidecar_output> fence, since it's prose from another model entering your context and should be treated as data, not instructions.

Context sharing. Your conversation history is passed automatically. Tune it:

• --context-turns <N> — max conversation turns to include (default 50).
• --context-since <duration> — time window (e.g. 2h); overrides turns.
• --context-max-tokens <N> — cap the context size (default 80000).
• --no-context — skip parent history entirely.

MCP inheritance. Amicus discovers the MCP servers your Claude Code session uses and passes them through, so the forked model has the same tools you do. Control it:

• --no-mcp — don't inherit any parent MCP servers.
• --exclude-mcp <name> — drop a specific server (repeatable).
• --mcp <name=url|name=command> — add one.

Safety. Amicus warns on file conflicts (a file changed externally while the session ran) and on context drift (the shared context may be stale relative to your current session), so a fold never silently overwrites newer work.

Commands

The am alias is interchangeable with amicus everywhere.

Every flag, every subcommand, every example — including the full amicus start option table, amicus fanout (supports --session-id, --council <name> as an alternative to --models), council presets, and every other command — lives in docs/usage.md, the canonical CLI reference. What follows here is just enough to see the shape of a run.

amicus status <id> output. Human-readable:

$ amicus status demo123
Task:     demo123
Status:   complete (terminal)
Elapsed:  5m 0s
Model:    google/gemini-2.5-flash

--json:

$ amicus status demo123 --json
{
  "taskId": "demo123",
  "status": "complete",
  "elapsed": "5m 0s",
  "version": "4.13.0",
  "model": "google/gemini-2.5-flash",
  "phase": "terminal"
}

amicus list --status accepts running, complete, error, timed-out, aborted, crashed, idle-timeout. Rows carry a TAG column (set at launch with --tag <t>); --search <q> filters by id/tag/briefing substring, --limit <n> caps the row count (0 = unlimited), and --all lists across every known project (council runs stay scoped to the current project — no cross-project index exists, and the listing discloses that). Full field-by-field docs (a running session's messages/STALLED reporting, wave-ID status shape, etc.) are in docs/usage.md.

Models

Amicus does not ship a frozen table of model names. Aliases and validation resolve against a live catalog fetched from provider APIs and cached at ~/.config/amicus/model-catalog.json (24-hour TTL; the fetch works without an API key). Run amicus models to see exactly what resolves on your machine — that's the source of truth, not this README.

amicus models                 # list the catalog
amicus models --search gemini # filter by substring

start/fanout validate your model against the catalog before launching (skip with --no-validate-model). You can also always bypass aliases and pass a full model ID directly — bare provider/model (canonical) or openrouter/provider/model (explicit override); see Routing below. Catalog internals, alias management, and the full-id passthrough table are in docs/usage.md § Models.

Routing

• Bare provider/model (e.g. openai/gpt-5.5, anthropic/claude-opus-4-8, google/gemini-3.6-flash) is the canonical, policy-routed form — Amicus routes it direct-first: your direct provider key when one is configured, falling back to OpenRouter automatically when only an OpenRouter key exists.
• openrouter/provider/model is an explicit override that always forces OpenRouter, even when a direct key is present — reach for it deliberately, or for gateway-only vendors with no direct integration (Qwen, Grok, Mistral, GLM, …).
• --gateway auto|direct|openrouter (CLI, also on the MCP tools) overrides routing for one call; auto is the direct-first default. routing.prefer in config.json ("direct" by default, or "openrouter") sets the global default.
• One-time migration notice: if you hold both an OpenRouter key and a direct key for a vendor, the first launch that resolves to that vendor under auto routing (the default) prints a one-time notice that routing moved to direct API; set routing.prefer: "openrouter" to restore the old all-OpenRouter behavior. The notice never fires when you explicitly pass --gateway direct — that's your own choice, not a migration.

Full details, the API-key/prefix table, and the migration notice are in docs/configuration.md.

MCP integration

The MCP server is auto-registered on install (Claude Code and Claude Desktop / Cowork). It exposes these tools:

The async pattern is start → status → read — amicus_start/amicus_fanout return immediately, then you poll amicus_status and call amicus_read; amicus_wait collapses that poll loop into one blocking call.

Legacy sidecar_* tool names were removed entirely in v2.0.0 — only amicus_* tools exist now. AMICUS_LEGACY_ALIASES=1 is a no-op left over from the v1.8.0 opt-in switch. See docs/SHIMS.md.

Manual registration and per-tool detail are in docs/usage.md § MCP Server.

Configuration

amicus setup is the recommended way to configure Amicus — it writes API keys to ~/.config/amicus/.env (0600) and persists your default model and aliases. Every environment variable (API keys, behavior tuning, headless poller, GUI/debug, process lifecycle) is documented in docs/configuration.md. v2.0.0 removed the legacy SIDECAR_* → AMICUS_* env-var mapping entirely; see docs/SHIMS.md for the removal record and rename table.

New to the disk footprint? The config tree's file-by-file contents, session storage layout, where (and whether) logs are written, config.json's exact shape, and full uninstall instructions all live in docs/configuration.md § Where things live.

JSON output

With --json, Amicus emits stable, versioned run/wave documents on stdout — built for scripting and agent consumption:

{
  "taskId": "...", "model": "...", "modelInput": "...", "agent": "...",
  "status": "complete", "summary": "...", "error": null,
  "createdAt": "...", "completedAt": "...", "durationMs": 0
}

The wave-document shape (for fanout), field meanings, and the full exit-code table are in docs/usage.md § JSON Output. Every --json document also has a published JSON Schema — see docs/schemas.md (shipped in the npm tarball under schemas/).

Windows

Amicus is first-class on Windows — developed and tested on Windows 11, no WSL required.

Most Claude-adjacent tooling assumes macOS/Linux; Amicus doesn't.

• The full unit suite runs green on Windows 11.
• Native-binary PATH handling resolves the OpenCode binary correctly under Windows.
• Session-path encoding is handled natively (the Claude project-path encoding that trips up naive ~/.claude/projects lookups is accounted for).
• For long briefings, --prompt-file sidesteps the ~32 KB Windows command-line argument cap.

Troubleshooting

Run amicus doctor first — it checks keys, catalog, OpenCode binary, Electron, skills, and MCP registration in one pass and prints a targeted fix for whatever's failing. For symptoms not covered below, or more diagnostic depth on any of these, see docs/troubleshooting.md.

Debug logging:

LOG_LEVEL=debug amicus start --model gemini --prompt "test" --no-ui

Documentation

Contributing

Contributions are welcome. The dev setup, git-hook wiring, and test commands live in CONTRIBUTING.md.

The autonomous Electron-UI testing approach (driving the real window over the Chrome DevTools Protocol) is documented in docs/electron-testing.md.

Built on OpenCode

Amicus is a harness built on top of OpenCode, the open-source AI coding engine. OpenCode provides the conversation runtime, tool-execution framework, agent system, and web UI. Amicus adds context sharing from Claude Code, the Electron shell, the fold/summary workflow, session persistence, parallel fanout waves, the multi-model council, and multi-client support (CLI, MCP, Cowork). OpenCode handles the hard parts of LLM interaction so Amicus can focus on the council-and-parallel-window workflow.

Attribution & License

Amicus is inspired by Claude Sidecar by John Renaldi, used under the MIT License. The original copyright (© 2025 John Renaldi) is preserved in full in LICENSE. The engine modifications, the multi-model council, and the skill bundling are © 2026 Christian Wagner, also under the MIT License. See LICENSE and NOTICE for the complete attribution.

MIT.