external-agents

@mrrlin-dev/external-agents — Multi-LLM MCP Server

Give your coding agent a pool of 40+ cheaper models to hand work off to. Cut your bill 10-100×.

Changelog: CHANGELOG.md

The problem this solves

You run Claude Code or Codex all day. Most of what it does — reading files to answer one question, running a test suite, renaming a symbol across 30 files, summarizing a diff — does not need a frontier model. But it all bills at frontier prices, on one account, against one rate limit.

Meanwhile you probably already have a handful of separate, mostly-free quota buckets sitting idle: a Google AI Studio key, a Groq key, OpenRouter's :free models, whatever agentic CLIs you're logged into.

external-agents turns those into one pool your primary agent can dispatch into. It picks a healthy provider per call, round-robins across buckets, and when one returns 429 it moves to a different provider and honors that provider's real reset time.

It's also a clean substrate for LLM-Council-style panels: one pick_agents call gives you N picks from N distinct providers, so a jury of models isn't secretly the same model four times.

🚀 2-minute setup

curl -fsSL https://raw.githubusercontent.com/mrrlin-dev/external-agents/main/install.sh | bash

The script installs the package, registers the MCP server with Claude Code and/or Codex (whichever it finds), and opens a local dashboard where you paste provider keys inline:

Then restart your MCP client. Your agent now has the tools.

npm install -g @mrrlin-dev/external-agents

# Register with whichever host(s) you use
claude mcp add external-agents external-agents-mcp
codex  mcp add external-agents -- external-agents-mcp

# Set up keys
external-agents ui        # opens http://127.0.0.1:4711

How much do I have to set up before this is useful?

Nothing, if you're already logged into an agentic CLI. Entries backed by a subscription you already have — claude, codex, cursor-agent, ollama, opencode, kiro-cli, agy — need no API key at all; they're usable the moment the binary is on your PATH and logged in.

Everything else is incremental. Each key you paste lights up more of the pool, and none of them are required:

Signup for each is about a minute. The dashboard links straight to the right page and has a paste box next to it.

What your agent gets

Two MCP tools, available automatically after setup:

• dispatch(agent_id, prompt) — run a prompt on a specific pool member. Auto-retries on a different provider if the first is rate-limited, and honors the provider's own reset time rather than a made-up 1-hour default.

  Pass cwd (an existing directory — a git worktree, say) and a direct CLI will inspect and edit files in place. cwd does not grant filesystem access to HTTP-based models; give those context with files instead. When cwd is a git repo, the files list that comes back is the git-changed set, not the whole tree.

• pick_agents(n, min_distinct_providers) — ask for N healthy agents from N different providers. This is the primitive for fan-out: jury-style review, self-consistency checks, your own consensus loop.

Both tools carry the routing guidance below in their descriptions, so any model reading the schema at runtime picks up the same bias.

Everything is also available from the terminal — external-agents pick, dispatch, status, stats, audit — if you'd rather script it than go through MCP. Run external-agents with no arguments for the full list.

What's in the pool

28 bundled entries, 25 enabled out of the box. The rest are paid upgrades that stay off until you opt in.

Got a second Google project? Google AI Studio can rate-limit an entire project at once, separately from each model's own per-minute limit — so a second key from the same account is a genuinely independent bucket, not a retry of the first. The dashboard's "+ Add another key" clones the provider's models under a new slug (google → google2 → google3…) and stores it in your local overlay, where it stays removable. The same applies to any key-based provider here.

Google's strong-tier model is the one bundled entry that's off by default: Gemini 3.1 Pro has a free-tier allowance of zero, so reaching it at all needs billing enabled. It stays bundled so you can flip it on if that's what you want. If you want a strong model for free instead, the pool has nine — Nemotron Ultra and Super on OpenRouter, gpt-oss 120B on Groq and Ollama, and Claude Opus / Gemini Pro through Antigravity.

DeepSeek ships disabled because its API is prepaid — with no key and no balance it can't answer anything, so it stays out of your pool until you add DEEPSEEK_API_KEY, at which point both entries turn themselves on.

Cerebras (removed in 0.13.0) and Z.ai (removed in 0.22.0) are no longer bundled — both need paid-provider setup. Add them back locally with add-model if you have a plan.

Missing a provider? Suggest it — the dashboard has a form that opens a pre-filled issue.

Keeping the pool honest

Providers deprecate models, free tiers rotate, keys expire. The bundled registry tells you what exists; only a real call tells you what your account can still reach.

external-agents audit                 # every entry with an HTTP transport
external-agents audit --provider google   # just one bucket

One round-trip per entry, concurrent per provider so you don't trip rate limits, and the verdicts are written to state.json — so the dashboard and dispatch immediately reflect ground truth:

• ✓ healthy — key works, model exists
• ⚠ needs_auth — 401/403, paste or refresh the key
• ✗ model_unavailable — key is fine, this model isn't on your tier
• ⏳ rate_limited — hit the current limit, will recover

Day to day, external-agents ui is the same information as a page: live provider state, usage, and a paste box per provider. It binds to loopback only. Individual entries have an on/off switch (external-agents toggle <id> --disabled) if you want one out of rotation without deleting anything.

Adding your own model

An internal endpoint, a beta model, anything not bundled:

external-agents add-model \
  --id kimi-k2-instruct \
  --provider groq \
  --model moonshotai/kimi-k2-instruct \
  --url https://api.groq.com/openai/v1/chat/completions \
  --env GROQ_API_KEY \
  --tags free,fast

That writes to ~/.local/state/external-agents/agents.local.yaml, layered over the bundled registry — same id replaces, new id appends. Package upgrades never clobber it. Full walkthrough: docs/adding-a-provider.md.

Routing philosophy — be smart, not lavish

pick_agents defaults to tier: "weak" on purpose. Most tasks don't need a frontier model.

Single-file edits, refactors, glue code, summaries, format conversions, well-scoped bug fixes, docstrings, test cases — a Gemini Flash, Groq gpt-oss, DeepSeek, or OpenRouter :free model gets you the same correct answer as Claude Opus or Codex Pro, faster and for a fraction of the cost.

Reach for strong tier (Claude Opus, Codex, DeepSeek Reasoner, Nemotron Ultra) when the task is genuinely one of these:

• Multi-step debugging with an unclear root cause
• Architecture or API-shape decisions
• Novel algorithms, math-heavy transforms
• Ambiguous requirements the model has to disambiguate

If a weak-tier agent gets it wrong, the first move is to sharpen the spec, not escalate the tier. escalate_to_pro is a retry lever, not a default — reaching for a bigger model hides prompt-engineering failures behind expensive compute, and you'll pay for it on every subsequent call too.

Related: --effort <level> controls reasoning depth where the provider supports it. Use high for planning, design, and review; leave it off for mechanical edits. See docs/effort.md for the verified per-agent table.

FAQ

Mrrlin uses this

Mrrlin is the platform this was extracted from. Its consensus gate — run on every design and every PR diff — is a four-reviewer panel, with reviewers pulled dynamically from this exact pool each round. Free-tier members mean the gate costs essentially nothing to run on every substantial change, and cross-model diversity beats any single reviewer.

You don't need Mrrlin to use the pattern. Build your own reviewer panel, self-consistency check, or jury-of-N verifier — the primitives are unopinionated.

external-agents is one piece of Mrrlin, an AI orchestration platform for solo developers and small teams.

License

MIT. Issues and pull requests welcome.