![\"The](\"./docs/cards/council-hero.svg\")
![\"One](\"./docs/cards/what-is-amicus.svg\")
![\"Anonymized](\"./docs/cards/blind-ballots.svg\")
![\"The](\"./docs/cards/dial-it-up.svg\")
![\"The](\"./docs/cards/priced-up-front.svg\")
![\"A](\"./docs/cards/same-table.svg\")
![\"A](\"./docs/cards/ship-gate.svg\")
` filters, `--limit` caps the rows, `--all` spans every known project (council runs: current project only — the CLI says so in-table). |\n| `amicus resume` | Reopen a previous session with full history. |\n| `amicus continue` | Start a new session building on a previous one. |\n| `amicus read` | Output a session's summary / conversation / metadata. |\n| `amicus status ` | One-shot status for a session or fan-out wave (human or `--json`; `--wave ` alternative spelling). |\n| `amicus watch ` | Live-render a fan-out wave, council run, or session from any terminal until it finishes — in-place table on a TTY, `--plain` milestone lines, or `--json` NDJSON; exit code maps the terminal state. `--ui` opens the [Council Workspace](./docs/council.md#council-workspace-gui) window instead (interactive-only, no `--json`). |\n| `amicus models` | List, search, refresh the catalog, or audit aliases. |\n| `amicus aliases` | Your model aliases — following / pinned; `--review` walks the update proposals, `--ui` does the same in the setup window, `--unpin ` removes a pin, `--json` for scripts; `--review --owner` (maintainers) reviews the shipped pins; after any command, a once-a-day notice when updates are waiting, and a weekly background catalog refresh (`aliasReview.autoRefresh: false` turns both off). |\n| `amicus doctor` | Diagnose your setup — keys, default model, catalog, aliases, shipped pins, OpenCode binary, Electron, skills, MCP registration, OpenRouter credit (`--json`; `--fix` self-heals what it can). |\n| `amicus spend` | Cross-run cost rollup from the spend ledger, with per-run attribution — total + per-model spend, tokens, and source mix, most-expensive first (`--wave`/`--council`/`--project`/`--model`/`--op`/`--failed` filter it, `--group-by` buckets it, `--since 7d` windows it; `--json` for a versioned doc; shows remaining OpenRouter credit when a key is configured). |\n| `amicus key` | Manage API keys non-interactively: `amicus key ` saves after live validation; `--remove`; bare `amicus key` lists providers. |\n| `amicus provider` | Add/list/test/remove local, OpenAI-compatible providers (LM Studio, Ollama, vLLM) — configured with `--preset` or `--url`, at **$0** marginal cost (`--json` on every subcommand). |\n| `amicus council` | Council math: `tally ` (deterministic tiers + ledger append), `stats` (reviewer reliability), `report [--md\\|--html]`, `validate ` (findings-block check, exit 0/2/1), `verdict [--decisions ] [-o ]` (build + write verdict.json). Presets: `save --models a,b,c`, `list [--json]`, `show [--json]` — see [Council presets](#council-presets) for the built-in `free`/`budget`/`frontier` benches. |\n| `amicus council run` | The headless council engine: Stage-1 reviews → anonymized cross-review → deterministic tally → non-Claude chair verdict, in one command with no Claude runtime. Add `--debate` for a Stage-2.5 rebuttal round (raisers defend/amend/withdraw, disputing judges re-vote) and `--claude-review ` to enter Claude's own review as judged review N+1. Writes a run directory with `verdict.json` (including `overallVerdict`) and `report.html` — see [docs/council.md](./docs/council.md#amicus-council-run). |\n| `amicus pack` | Save a full run configuration — bench, chair/critic/lenses, options, briefing template — and invoke it by name: `save --kind council\\|fanout\\|solo [flags]` (or `--from-run `), `list`, `show `, `rm `. `--pack ` on `start`/`fanout`/`council run` loads one; explicit flags always override it. See [docs/usage.md § Policy packs](./docs/usage.md#policy-packs). |\n| `amicus template` | `list`/`show ` a briefing template. `--template [--artifact ] [--var k=v]` on `start`/`fanout`/`council run` renders one before the briefing is sent. See [docs/usage.md § Briefing templates](./docs/usage.md#briefing-templates). |\n| `amicus abort` | Abort a running session (or `--all`). |\n| `amicus setup` | Configure default model, API keys, and aliases. |\n| `amicus update` | Update to the latest version. |\n| `amicus mcp` | Start the MCP server (stdio transport). |\n| `amicus init` | Re-run skill install + MCP registration on demand — `--claude`/`--desktop` to scope it, `--json` for per-step status. For plugin-channel / `--ignore-scripts` installs (which skip the npm postinstall), a failed postinstall, or repairing deleted `~/.claude` state. |\n\nThe `am` alias is interchangeable with `amicus` everywhere.\n\n**Every flag, every subcommand, every example** — including the full `amicus start` option table, `amicus fanout` (supports `--session-id`, `--council ` as an alternative to `--models`), council presets, and every other command — lives in **[docs/usage.md](./docs/usage.md)**, the canonical CLI reference. What follows here is just enough to see the shape of a run.\n\n`amicus status ` output. Human-readable:\n\n```\n$ amicus status demo123\nTask: demo123\nStatus: complete (terminal)\nElapsed: 5m 0s\nModel: google/gemini-2.5-flash\n```\n\n`--json`:\n\n```\n$ amicus status demo123 --json\n{\n \"taskId\": \"demo123\",\n \"status\": \"complete\",\n \"elapsed\": \"5m 0s\",\n \"version\": \"4.14.2\",\n \"model\": \"google/gemini-2.5-flash\",\n \"phase\": \"terminal\"\n}\n```\n\n`amicus list --status` accepts `running`, `complete`, `error`, `timed-out`, `aborted`, `crashed`, `idle-timeout`. Rows carry a `TAG` column (set at launch with `--tag `); `--search ` filters by id/tag/briefing substring, `--limit` 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](./docs/usage.md).\n\n---\n\n## Models\n\nAmicus 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.\n\n```bash\namicus models # list the catalog\namicus models --search gemini # filter by substring\n```\n\n`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](./docs/usage.md#amicus-models--the-model-catalog)**.\n\n \n\n### Routing\n\n- **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.\n- **`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, …).\n- **`--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.\n- **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.\n\nFull details, the API-key/prefix table, and the migration notice are in **[docs/configuration.md](./docs/configuration.md)**.\n\n---\n\n## MCP integration\n\nThe MCP server is auto-registered on install (Claude Code and Claude Desktop / Cowork). It exposes these tools:\n\n| Tool | What it does |\n|------|--------------|\n| `amicus_start` | Spawn a session; returns a task ID immediately. |\n| `amicus_status` | Poll a task (or a fanout wave) for completion. |\n| `amicus_wait` | Block inside one tool call until a session/wave finishes or the wait window closes. |\n| `amicus_read` | Read results: summary, conversation, metadata, or JSON. |\n| `amicus_list` | List past sessions (`tag` field; `search` filters by id/tag/briefing substring). |\n| `amicus_resume` | Reopen a session. |\n| `amicus_continue` | New session building on a previous one. |\n| `amicus_abort` | Stop a running session. |\n| `amicus_setup` | Open the setup wizard. |\n| `amicus_guide` | Return usage guidance (model choice, briefings, polling). |\n| `amicus_fanout` | Launch a same-prompt wave; returns `{ waveId, taskIds[] }`. |\n| `amicus_council_tally` | Aggregate a council wave's reviews into a scored tally. |\n| `amicus_council_stats` | Reviewer-reliability stats from past council runs. |\n| `amicus_verdict` | Build the final council verdict from a tally + decisions; writes `
/report.html` when `render:true` and `outDir` are given. |\n| `amicus_council_run` | Run the full headless council engine (Stage-1 reviews → anonymized cross-review → tally → chair verdict); returns `{ runId, runDir }`, async. |\n| `amicus_spend` | Read-only cross-run cost rollup from the spend ledger (mirrors the CLI `amicus spend` flags). |\n\nThe 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.\n\n> 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](./docs/SHIMS.md).\n\nManual registration and per-tool detail are in **[docs/usage.md § MCP Server](./docs/usage.md#mcp-server)**.\n\n---\n\n## Configuration\n\n`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](./docs/configuration.md)**. v2.0.0 removed the legacy `SIDECAR_*` → `AMICUS_*` env-var mapping entirely; see [docs/SHIMS.md](./docs/SHIMS.md) for the removal record and rename table.\n\n**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](./docs/configuration.md#where-things-live)**.\n\n---\n\n## JSON output\n\nWith `--json`, Amicus emits stable, versioned run/wave documents on stdout — built for scripting and agent consumption:\n\n```json\n{\n \"taskId\": \"...\", \"model\": \"...\", \"modelInput\": \"...\", \"agent\": \"...\",\n \"status\": \"complete\", \"summary\": \"...\", \"error\": null,\n \"createdAt\": \"...\", \"completedAt\": \"...\", \"durationMs\": 0\n}\n```\n\nThe wave-document shape (for `fanout`), field meanings, and the full exit-code table are in **[docs/usage.md § JSON Output](./docs/usage.md#json-output)**. Every `--json` document also has a published JSON Schema — see **[docs/schemas.md](./docs/schemas.md)** (shipped in the npm tarball under `schemas/`).\n\n---\n\n## Windows\n\nAmicus is **first-class on Windows** — developed and tested on Windows 11, no WSL required.\n\nMost Claude-adjacent tooling assumes macOS/Linux; Amicus doesn't.\n\n- The full unit suite runs green on Windows 11.\n- Native-binary PATH handling resolves the OpenCode binary correctly under Windows.\n- Session-path encoding is handled natively (the Claude project-path encoding that trips up naive `~/.claude/projects` lookups is accounted for).\n- For long briefings, `--prompt-file` sidesteps the ~32 KB Windows command-line argument cap.\n\n---\n\n## Troubleshooting\n\nRun `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](./docs/troubleshooting.md)**.\n\n| Symptom | Likely cause | Fix |\n|---------|--------------|-----|\n| \"council review this\" does nothing | The `second-opinion` skill isn't installed | Check `~/.claude/skills/second-opinion/SKILL.md` exists; re-run `npm install -g amicus` (postinstall installs both skills) |\n| `npm install -g amicus` fails with `EEXIST: … claude-sidecar` | The old upstream `claude-sidecar` package is still installed globally; npm won't overwrite another package's bin shims | `npm uninstall -g claude-sidecar`, then `npm install -g amicus`. Your keys and past sessions are not lost, but v2.0.0 no longer reads the old paths automatically — see [docs/SHIMS.md](./docs/SHIMS.md) for the one-time migration steps (rename `~/.config/sidecar/` and any `.claude/sidecar_sessions/` dirs). |\n| Install fails partway, or `amicus doctor` reports the OpenCode binary \"not found\" | A **transient** error during the OpenCode engine's own postinstall (a spawn `ENOENT`, or an antivirus file-lock while it lays down its 11 per-platform binaries) can roll back the whole atomic install — retrying usually succeeds | Just re-run `npm install -g amicus`. If it still fails, clear the cache first: `npm cache clean --force && npm install -g amicus`. |\n| `401` / auth error | No usable key for the model's vendor — bare `provider/model` ids fall back to `OPENROUTER_API_KEY` automatically, so this means neither the direct key nor an OpenRouter key is configured (or `--gateway direct`/`openrouter` forced a gateway whose key is missing) | Run `amicus setup`, or `amicus key ` to add the missing key; see [Routing](#routing). |\n| `402` / \"Payment Required\" on first council review / `start` / `fanout` call | Your OpenRouter key is real but has no credit. Key save (`amicus key openrouter ` or the setup wizard's key step) only checks that the key **authenticates** — it doesn't check balance, so a zero-credit key saves cleanly and only fails later, on the first real model call. (The `amicus council` subcommand itself is deterministic math and never calls a model.) | Add credit at [openrouter.ai/credits](https://openrouter.ai/credits), **or** switch to a zero-cost council: `amicus setup` → option 2 (Free OpenRouter council) builds one from live `:free`-suffixed models and saves it as `councils.free` — then run `amicus fanout --council free …`. See [Free council (zero-cost)](#free-council-zero-cost) above. |\n| Every direct `anthropic/…` model (`haiku`, `sonnet`, `opus`, `claude`) errors `Not Found` in ~2 s at zero tokens, but the same model works via `openrouter/anthropic/…` | An inherited host-form `ANTHROPIC_BASE_URL` (missing `/v1`) — the Anthropic-SDK convention, not OpenCode's; a shell spawned by Claude Code sets it for you. **Since v4.6.2 amicus normalizes this to ` /v1` automatically** (a provider-config override, announced once on stderr) — the model id, alias, and key were never the problem, and now neither is the URL, unless `AMICUS_BASE_URL_NORMALIZE=0` is set or the path is nonstandard. | Should now self-heal — confirm with `amicus doctor`'s `anthropic-base-url` row (shows the value seen + its treatment). Still failing: unset `AMICUS_BASE_URL_NORMALIZE` if you set it, or `export ANTHROPIC_BASE_URL=https://api.anthropic.com/v1` / unset the var entirely / pass `--gateway openrouter`. In a council a dead seat **degrades the run instead of failing it** — smoke-test each seat with one throwaway `amicus start` before paying for a council. See [docs/troubleshooting.md](./docs/troubleshooting.md#every-direct-anthropic-model-fails-with-not-found). |\n| `Model 'X' is unverified against the direct catalog; attempting anyway` for a model that plainly exists | Not a claim the model is wrong — amicus **couldn't check**. That vendor's direct catalog fetch failed (usually a stale or truncated stored key), leaving its namespace empty, and an empty namespace never blocks a launch. The engine may still run the model from its own credential store, so a working model warns forever. | `amicus models --refresh` and watch for a provider that stays empty; re-save the good key with `amicus key `. See [docs/troubleshooting.md](./docs/troubleshooting.md#model-x-is-unverified-against-the-direct-catalog-attempting-anyway). |\n| Session not found | No session matches the given ID | Run `amicus list`, or omit `--session-id` to use the most recent. |\n| No conversation history found | Project-path encoding | Check `~/.claude/projects/`; `/` and `_` in the project path are encoded as `-` in the directory name. |\n| Headless run never finishes | Task is bigger than the default timeout | Raise it: `--timeout 30`. |\n| Wrong session picked up | Multiple active sessions resolve ambiguously | Pass `--session-id` explicitly. |\n| Fold summary looks corrupted | Debug output leaking into stdout | Re-run with `LOG_LEVEL=debug` to see what's printing. |\n| Model fails catalog validation | The model isn't in the cached catalog (renamed, or cache stale) | `amicus models --refresh`, or bypass with `--no-validate-model`. |\n| `fanout` exits `2` | Partial wave — at least one leg failed | Read the wave document's `legs[]` and inspect each failed leg's `status` / `error`. |\n\n**Debug logging:**\n\n```bash\nLOG_LEVEL=debug amicus start --model gemini --prompt \"test\" --no-ui\n```\n\n---\n\n## Documentation\n\n| Doc | Description |\n|-----|-------------|\n| [docs/usage.md](./docs/usage.md) | The complete CLI & MCP reference — every flag, every subcommand, every example. |\n| [docs/council.md](./docs/council.md) | Council pipeline reference: `tally`/`verdict`/`report` schemas, provenance, and a worked example. |\n| [docs/schemas.md](./docs/schemas.md) | Published JSON Schemas for every `--json` document (result + council families). |\n| [docs/configuration.md](./docs/configuration.md) | Full configuration and environment reference. |\n| [docs/architecture.md](./docs/architecture.md) | How the engine, Electron shell, and context sharing fit together. |\n| [docs/opencode-integration.md](./docs/opencode-integration.md) | How Amicus drives the OpenCode runtime. |\n| [docs/troubleshooting.md](./docs/troubleshooting.md) | Extended troubleshooting. |\n| [docs/electron-testing.md](./docs/electron-testing.md) | Chrome DevTools Protocol patterns for UI testing. |\n| [docs/testing.md](./docs/testing.md) | Test suite layout and how to run it. |\n| [docs/CITATIONS.md](./docs/CITATIONS.md) | How to cite one file from another so the citation cannot rot, and what the citation gate enforces. |\n| [docs/publishing.md](./docs/publishing.md) | Release and publish process. |\n| [docs/SHIMS.md](./docs/SHIMS.md) | v2.0.0 removal record for the pre-rebrand `sidecar*` compatibility shims — what was removed and how to migrate. |\n| [skills/second-opinion/SKILL.md](./skills/second-opinion/SKILL.md) | The LLM Council skill. |\n| [skills/sidecar/SKILL.md](./skills/sidecar/SKILL.md) | The `sidecar` chat skill. |\n| [evals/README.md](./evals/README.md) | End-to-end eval harness for LLM interactions. |\n\n---\n\n## Contributing\n\nContributions are welcome. The dev setup, git-hook wiring, and test commands live in **[CONTRIBUTING.md](./CONTRIBUTING.md)**.\n\nThe autonomous Electron-UI testing approach (driving the real window over the Chrome DevTools Protocol) is documented in **[docs/electron-testing.md](./docs/electron-testing.md)**.\n\n---\n\n## Built on OpenCode\n\nAmicus is a harness built on top of [**OpenCode**](https://opencode.ai), 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.\n\n---\n\n## Attribution & License\n\nAmicus is inspired by [**Claude Sidecar**](https://github.com/jrenaldi79/sidecar) by [John Renaldi](https://github.com/jrenaldi79), used under the MIT License. The original copyright (© 2025 John Renaldi) is preserved in full in [LICENSE](./LICENSE). The engine modifications, the multi-model council, and the skill bundling are © 2026 Christian Wagner, also under the MIT License. See [LICENSE](./LICENSE) and [NOTICE](./NOTICE) for the complete attribution.\n\n**MIT.**\n","readmeFilename":"README.md"}
![\"Direct](\"./docs/cards/build-the-bench.svg\")