[codex] add metaswarm review adapter integration

.env.example

@@ -52,7 +52,10 @@ LONGCAT_API_KEY=
 
 # ---------------------------------------------------------------------------
 # Zero-setup providers (no key needed — included automatically):
+#   • Pollinations            (anonymous/keyless)
 #   • OVHcloud AI Endpoints  (anonymous/keyless)
+#   • Kilo Gateway           (anonymous/keyless)
+#   • OpenCode Zen           (anonymous/keyless)
 #   • LLM7                    (works without a key; set LLM7_API_KEY for more)
 # So freellmpool works out of the box even with this whole file empty.
 # ---------------------------------------------------------------------------

CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/), and the project aims to follow
 [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+### Added
+- Experimental metaswarm review adapter integration, with setup docs and no-key
+  smoke coverage for fail-closed `auth_missing` behavior.
+
 ## [0.11.4] — 2026-06-17
 
 MCP Registry verification metadata release.

FAQ.md

@@ -18,6 +18,7 @@ not encode data residency, this table says so instead of guessing.
 | `llm7` | `https://api.llm7.io/v1` | Key optional | LLM7's privacy policy says it operates from the United Kingdom. | Optional-token gateway; prompts go to LLM7 and whatever upstream serving path it uses. |
 | `ovh` | `https://oai.endpoints.kepler.ai.cloud.ovh.net/v1` | Keyless | OVHcloud describes AI Endpoints as a privacy-focused OVHcloud service; the catalog does not pin a region. | Strongest keyless privacy posture in this catalog, but still a third-party hosted API. |
 | `kilo` | `https://api.kilo.ai/api/gateway` | Keyless | Kilo Code Inc.; endpoint region is not stated in the catalog. | Gateway docs warn not to submit personal or confidential data; treat free routes as logged. |
+| `opencode` | `https://opencode.ai/zen/v1` | Keyless | OpenCode Zen endpoint region is not stated in the catalog. | Anonymous gateway; live free routes may change quickly, so do not send secrets unless OpenCode's current policy fits your use case. |
 | `huggingface` | `https://router.huggingface.co/v1` | `HF_TOKEN` | Hugging Face says the company and servers are in the United States and data may be processed elsewhere. | Router endpoint; your key and prompt go to Hugging Face's routed inference service. |
 | `groq` | `https://api.groq.com/openai/v1` | `GROQ_API_KEY` | Groq, Inc.; endpoint region is not stated in the catalog. | Direct provider API using your Groq key; check Groq's current service/privacy terms for retention. |
 | `cerebras` | `https://api.cerebras.ai/v1` | `CEREBRAS_API_KEY` | Cerebras Systems Inc.; endpoint region is not stated in the catalog. | Direct provider API using your Cerebras key; check Cerebras' current policy before sensitive prompts. |

README.md

@@ -4,9 +4,9 @@
 
 ![freellmpool tokenmax terminal demo](assets/demo.svg)
 
-![200+ models, 18 providers, $0 to start](assets/tokenmax-results.svg)
+![200+ models, 19 providers, $0 to start](assets/tokenmax-results.svg)
 
-Pool the free tiers of 18 LLM providers (200+ live-validated, 300+ cataloged
+Pool the free tiers of 19 LLM providers (200+ live-validated, 300+ cataloged
 models) behind one OpenAI-compatible endpoint — as a CLI, a Python library, or a
 local proxy. Works with no API keys.
 
@@ -39,8 +39,9 @@ rate limits, and daily cap. freellmpool puts them in one pool: it sends each
 request to a provider you have access to, fails over to the next when one is rate
 limited or down, and tracks per-day usage so you get the most out of every tier.
 
-Several providers (Pollinations, OVHcloud, and Kilo Gateway) need no API key, so
-the quickstart above answers immediately.
+Several providers (Pollinations, OVHcloud, Kilo Gateway, and OpenCode Zen) need
+no API key, and LLM7 works without one, so the quickstart above answers
+immediately.
 
 Add keys for the other providers to unlock more models and higher limits.
 
@@ -168,7 +169,9 @@ Endpoints: `/v1/chat/completions` (token streaming, tool calling), `/v1/embeddin
 `/v1/audio/transcriptions` (Whisper, multipart upload), `/v1/responses`, `/v1/messages`,
 `/v1/models`, and a `/dashboard` page showing usage.
 Setup snippets for specific tools are in [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md)
-and [docs/AGENTS.md](docs/AGENTS.md).
+and [docs/AGENTS.md](docs/AGENTS.md). The repo also includes an experimental
+[metaswarm review adapter](integrations/metaswarm) for using `freellmpool` as an
+external-tools reviewer/second opinion.
 
 ## As a library
 
@@ -353,7 +356,7 @@ Architecture notes: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
 | Tool | Keyless start | # providers | Failover | MCP server | CLI | Transcription | Local/self-hosted | License |
 |---|---|---:|---|---|---|---|---|---|
-| **freellmpool** | Yes: Pollinations, OVHcloud, Kilo Gateway; LLM7 is key-optional | 18 built-in chat providers | Yes: tries the next provider on rate limits, timeouts, 5xx, empty replies, and transport errors | Yes: `freellmpool mcp` | Yes: `freellmpool ask`, `tokenmax`, `providers`, `proxy`, and more | Yes: OpenAI-compatible `/v1/audio/transcriptions` with provider failover | Yes: local Python package and local proxy | MIT |
+| **freellmpool** | Yes: Pollinations, OVHcloud, Kilo Gateway, OpenCode Zen; LLM7 is key-optional | 19 built-in chat providers | Yes: tries the next provider on rate limits, timeouts, 5xx, empty replies, and transport errors | Yes: `freellmpool mcp` | Yes: `freellmpool ask`, `tokenmax`, `providers`, `proxy`, and more | Yes: OpenAI-compatible `/v1/audio/transcriptions` with provider failover | Yes: local Python package and local proxy | MIT |
 | OpenRouter free models | No: OpenRouter account/API key required | One hosted OpenRouter account routing across many upstreams; the free-model router currently lists free variants | Yes: OpenRouter handles provider routing/fallbacks | Not a native MCP server; OpenRouter docs show MCP-client/tool patterns | No first-party local CLI in the docs checked | Yes: OpenRouter now documents audio transcription APIs | No: hosted service | Proprietary service |
 | LiteLLM | No: bring provider keys or hosted LiteLLM credentials | 100+ LLM providers | Yes: router/fallbacks, including transcription fallbacks | Yes: LiteLLM Proxy includes an MCP Gateway | Yes: SDK/proxy command surface, not a one-shot free-model CLI | Yes: `/audio/transcriptions` support | Yes: self-host the proxy or use hosted LiteLLM | MIT for core repo; commercial license for enterprise-only pieces |
 | FreeLLMAPI | No: add your own free-tier provider keys; keyless providers can be configured after setup | 16 free-tier providers plus custom OpenAI-compatible endpoints | Yes: fallback chain on 429, 5xx, and timeouts | No native MCP server in the README checked | Dashboard/server, desktop app, and Docker; no first-class one-shot CLI in the README checked | No: `/v1/audio/*` is listed as not yet supported | Yes: self-hosted Node/Docker proxy | MIT |
@@ -373,7 +376,7 @@ audio transcription docs; FreeLLMAPI's README.
 
 **Is there a free, OpenAI-compatible LLM API gateway?** Yes — freellmpool is a free,
 MIT-licensed gateway that exposes one OpenAI-compatible endpoint backed by the free
-tiers of 18 providers. `pip install freellmpool` and point any OpenAI client at the
+tiers of 19 providers. `pip install freellmpool` and point any OpenAI client at the
 local proxy.
 
 **How do I use multiple free LLM APIs at once?** freellmpool pools them: each request
@@ -387,9 +390,10 @@ Code, set `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` so `/v1/models` is disc
 through the Anthropic bridge. See `freellmpool code <agent>`. (Claude Code path is
 experimental: text + tools, no vision.)
 
-**Do I need an API key?** No — Pollinations, OVHcloud, and Kilo Gateway work with no key, so a fresh
-install answers immediately. Add free keys for the other providers for more models and
-higher limits.
+**Do I need an API key?** No — Pollinations, OVHcloud, Kilo Gateway, and OpenCode
+Zen work with no key, and LLM7 is key-optional, so a fresh install answers
+immediately. Add free keys for the other providers for more models and higher
+limits.
 
 **Is it free and open source?** Yes, MIT-licensed. More at the
 [project page](https://0xzr.github.io/freellmpool/).

docs/ACCOUNTS.md

@@ -5,8 +5,9 @@
 all of them — even **one** key gets you going. Start with Groq + Cerebras (the
 two fastest, most generous, and quickest to sign up for), then add more later.
 
-> **No keys at all?** freellmpool still works: **OVHcloud**, **Kilo Gateway**, and
-> **Pollinations** are keyless (anonymous) and **LLM7** works without a key. So
+> **No keys at all?** freellmpool still works: **Pollinations**, **OVHcloud**,
+> **Kilo Gateway**, and **OpenCode Zen** are keyless (anonymous) and **LLM7**
+> works without a key. So
 > `freellmpool ask "hi"` runs the moment you install. The keys below just add more
 > models, higher limits, and better failover.
 
@@ -83,15 +84,20 @@ That's enough to start. Run `freellmpool ask "hello"`.
 1. <https://longcat.chat> → developer/API keys.
 2. `export LONGCAT_API_KEY=...`
 
-### OVHcloud, Kilo Gateway & LLM7 — *no signup needed*
-Nothing to do — OVHcloud and Kilo Gateway are anonymous, and LLM7 works without a
-key. For higher LLM7 limits you can optionally grab a token at
+### Pollinations, OVHcloud, Kilo Gateway, OpenCode Zen & LLM7 — *no signup needed*
+Nothing to do — Pollinations, OVHcloud, Kilo Gateway, and OpenCode Zen are
+anonymous, and LLM7 works without a key. For higher LLM7 limits you can
+optionally grab a token at
 <https://token.llm7.io> and `export LLM7_API_KEY=...`.
 
 **Kilo Gateway** is a keyless OpenAI-compatible aggregator of free models
 (~200 req/hour per IP). Heads up: its free routes may log prompts — don't send
 confidential data through Kilo models (`kilo/…`).
 
+**OpenCode Zen** is a keyless OpenAI-compatible gateway with a small set of
+live-validated free routes. Treat it like other anonymous routes: useful for
+quick starts, not for confidential prompts.
+
 ### Cloudflare Workers AI — *needs two values*
 1. Account ID: Cloudflare dashboard → **Workers & Pages** (right sidebar shows
    your Account ID), or **Workers AI** → **Use REST API**.

docs/AGENTS.md

@@ -62,6 +62,20 @@ codex --config model_provider=openai   # or set base URL in ~/.codex/config.toml
 > running Codex/agents on free inference for everyday coding; tool-calling and
 > richer Responses features are a work in progress.
 
+## Metaswarm external-tools review
+
+Metaswarm can use `freellmpool` as a review-only external tool. The integration
+is in [`integrations/metaswarm`](../integrations/metaswarm): copy
+`freellmpool-review-adapter.sh` into `.metaswarm/adapters/freellmpool.sh`, then
+add it to `.metaswarm/external-tools.yaml` with roles `review` and
+`second_opinion`.
+
+The adapter is deliberately not an implementer. It reviews a worktree diff
+against a spec/rubric, runs a configurable strong-model panel through
+`freellmpool`, and emits a metaswarm-style JSON envelope. If no strong provider
+key is configured (`MISTRAL_API_KEY`, `NVIDIA_API_KEY`, or `OPENROUTER_API_KEY`
+by default), it returns `error_type: "auth_missing"` before any provider call.
+
 ## aider (AI pair programming in your terminal)
 
 ```bash

docs/GITHUB_DISCOVERY.md

@@ -14,7 +14,7 @@ gh repo view 0xzr/freellmpool --json description,repositoryTopics,url,isPrivate
 
 Current About description:
 
-> Pool the free tiers of 18 LLM providers (Groq, Cerebras, NVIDIA NIM, Gemini, OpenRouter, Cloudflare, Hugging Face...) behind one OpenAI-compatible /v1 endpoint. Free, zero-config, automatic failover. Codex/agent ready.
+> Pool the free tiers of 19 LLM providers (Groq, Cerebras, NVIDIA NIM, Gemini, OpenRouter, Cloudflare, Hugging Face...) behind one OpenAI-compatible /v1 endpoint. Free, zero-config, automatic failover. Codex/agent ready.
 
 Current topics are already at GitHub's 20-topic limit:
 
@@ -31,7 +31,7 @@ P9 gap topics missing from the live repo:
 
 Recommended description (107 chars):
 
-> Free LLM API pool: 18 LLM providers, 200+ live models, 300+ cataloged models, zero keys to start, failover.
+> Free LLM API pool: 19 LLM providers, 200+ live models, 300+ cataloged models, zero keys to start, failover.
 
 Recommended 20-topic set:
 
@@ -47,7 +47,7 @@ Operator command after merge:
 
 ```bash
 gh repo edit 0xzr/freellmpool \
-  --description "Free LLM API pool: 18 LLM providers, 200+ live models, 300+ cataloged models, zero keys to start, failover." \
+  --description "Free LLM API pool: 19 LLM providers, 200+ live models, 300+ cataloged models, zero keys to start, failover." \
   --remove-topic ai \
   --remove-topic gateway \
   --remove-topic llm \

docs/INTEGRATIONS.md

@@ -45,6 +45,26 @@ spread quota). Full guide: <https://0xzr.github.io/freellmpool/run-opencode-on-f
 - [`integrations/opencode`](../integrations/opencode) — a server plugin adding
   `freellmpool_status` and `freellmpool_models` tools and a served-model toast.
 
+### metaswarm
+[`integrations/metaswarm`](../integrations/metaswarm) contains an experimental
+review-only adapter for metaswarm `external-tools`. It lets metaswarm call
+`freellmpool` as an adversarial reviewer or second opinion and returns the same
+JSON envelope style as other metaswarm adapters.
+
+Copy the adapter into your project:
+
+```bash
+mkdir -p .metaswarm/adapters
+cp integrations/metaswarm/freellmpool-review-adapter.sh .metaswarm/adapters/freellmpool.sh
+chmod +x .metaswarm/adapters/freellmpool.sh
+```
+
+Then add it to `.metaswarm/external-tools.yaml` as a `review` /
+`second_opinion` adapter. Configure at least one strong review provider
+(`MISTRAL_API_KEY`, `NVIDIA_API_KEY`, or `OPENROUTER_API_KEY`) before enabling it;
+without those keys it fails closed with `error_type: "auth_missing"` and makes no
+provider calls. Full setup: [`integrations/metaswarm/README.md`](../integrations/metaswarm/README.md).
+
 ### aider
 ```bash
 export OPENAI_API_BASE=http://localhost:8080/v1

docs/best-free-llm-api-gateway.html

@@ -27,7 +27,7 @@
 <h1>Best free LLM API gateway (2026)</h1>
 
 <p class="lead"><strong>For using free LLM tiers specifically, the best free, open-source gateway is
-<a href="https://github.com/0xzr/freellmpool">freellmpool</a>: it pools the free tiers of 18 providers
+<a href="https://github.com/0xzr/freellmpool">freellmpool</a>: it pools the free tiers of 19 providers
 behind one OpenAI-compatible endpoint, installs with <code>pip</code>, works with no API key to start,
 and ships as a CLI, a Python library, a local proxy, and an MCP server. LiteLLM is the best choice if you
 bring your own keys and want a mature multi-provider SDK; OpenRouter is best if you want one paid bill for

docs/capacity-management.html

@@ -43,7 +43,7 @@ <h1>Know which free LLM tiers are usable right now</h1>
 daily caps fill up. <a href="https://github.com/0xzr/freellmpool">freellmpool</a> ships capacity tools
 that tell you, locally, which of your free providers are usable <em>right now</em>, which are near their
 quota, and which keys to add next.</strong> freellmpool is a free, open-source tool that pools the free
-tiers of 18 LLM providers behind one OpenAI-compatible endpoint; these commands keep that pool healthy.</p>
+tiers of 19 LLM providers behind one OpenAI-compatible endpoint; these commands keep that pool healthy.</p>
 
 <pre><code>pip install freellmpool
 freellmpool capacity status --target 5</code></pre>

docs/free-alternative-to-openrouter.html

@@ -38,7 +38,7 @@ <h2>How they differ</h2>
 <tr><th></th><th>OpenRouter</th><th>freellmpool</th></tr>
 <tr><td>Cost</td><td>Pay per token (some free models)</td><td>Free — pools providers' free tiers</td></tr>
 <tr><td>Hosting</td><td>Hosted service</td><td>Local, open source (MIT)</td></tr>
-<tr><td>Keyless start</td><td>No (account + key)</td><td>Yes (3 keyless providers)</td></tr>
+<tr><td>Keyless start</td><td>No (account + key)</td><td>Yes (4 keyless providers, plus LLM7 key-optional)</td></tr>
 <tr><td>Interface</td><td>API</td><td>CLI + Python library + proxy + MCP server</td></tr>
 <tr><td>Failover</td><td>Yes</td><td>Yes</td></tr>
 </table>
@@ -62,7 +62,7 @@ <h3>Is there a free version of OpenRouter?</h3>
 open-source path, freellmpool pools the LLM providers' own free tiers behind one OpenAI-compatible
 endpoint and is keyless to start.</p>
 <h3>Can freellmpool use OpenRouter too?</h3>
-<p>Yes — OpenRouter is one of the 18 providers freellmpool can pool, so its free models become part of
+<p>Yes — OpenRouter is one of the 19 providers freellmpool can pool, so its free models become part of
 the failover pool alongside Groq, Cerebras, Gemini and the rest.</p>
 
 <p class="meta">Part of <a href="https://github.com/0xzr/freellmpool">freellmpool</a> (MIT, free, open source). Updated 2026-06-03.</p>