@mrrlin-dev/external-agents 0.2.10 → 0.3.0

package/README.md

@@ -1,12 +1,17 @@
 # @mrrlin-dev/external-agents
 
+[![Install to Claude Code](https://img.shields.io/badge/Install_to-Claude_Code-4a90e2?style=for-the-badge&logo=anthropic&logoColor=white)](#claude-code)
+[![Install to Codex](https://img.shields.io/badge/Install_to-Codex-24292f?style=for-the-badge&logo=openai&logoColor=white)](#codex)
+[![One-command install](https://img.shields.io/badge/curl_%7C_bash-one_command-4a8?style=for-the-badge)](#one-command-install)
+[![npm](https://img.shields.io/npm/v/@mrrlin-dev/external-agents?style=for-the-badge)](https://www.npmjs.com/package/@mrrlin-dev/external-agents)
+
 **Cut your LLM bill by 10-100x by fanning work across free tiers of a dozen providers.**
 
 `external-agents` is an MCP server + CLI that routes work from your primary coding agent (Claude Code, Codex, Cursor) to a **pool of 20+ free-tier LLMs** — Gemini, Groq, Cerebras, OpenRouter :free, Z.ai, Ollama Cloud, and paid tiers of DeepSeek — via one clean surface: round-robin, cooldown-aware, auto-fallback on 429, with a local dashboard for setting keys and tracking usage.
 
 **The core value is economic.** You have separate free-tier quotas at Google + Groq + Cerebras + OpenRouter + Z.ai. `external-agents` treats them as **one pool of tokens** and dispatches to the next healthy bucket. What used to be one 30-req/min Gemini limit is now ~150 req/min across five providers, all at $0 — enough to run entire agentic loops (implementations, reviews, refactors) that would burn $10-100/day on a single paid model.
 
-**It's also the substrate for LLM-consensus** — the "ask N different models the same question, adjudicate" pattern popularized in [LLM-as-a-Judge](https://arxiv.org/abs/2306.05685) work and echoed frequently by [Andrej Karpathy](https://x.com/karpathy) as an "LLM Council" idea: an ensemble of frontier models routinely beats any single one. `pick_agents` gives you N distinct-provider picks in one call, so a "fleet of subagents deliberating in parallel" is one primitive away. **[Mrrlin](https://mrrlin.com) uses exactly this** — its consensus gate resolves two dynamic terminal reviewers from this pool every round, so every design and every diff gets stress-tested by different model families before it merges.
+**It's also the substrate for LLM-consensus** — the "ask N different models the same question, adjudicate" pattern — see [karpathy/llm-council](https://github.com/karpathy/llm-council) ("LLM Council works together to answer your hardest questions") and the broader [LLM-as-a-Judge](https://arxiv.org/abs/2306.05685) literature. An ensemble of frontier models routinely beats any single one. `pick_agents` gives you N distinct-provider picks in one call, so a "fleet of subagents deliberating in parallel" is one primitive away. **[Mrrlin](https://mrrlin.com) uses exactly this** — its consensus gate resolves two dynamic terminal reviewers from this pool every round, so every design and every diff gets stress-tested by different model families before it merges.
 
 Beyond savings and consensus, you also get the zoo-manager niceties: per-provider auth, cooldowns keyed to the *provider's* reset time (not a made-up default), quota tracking in a local JSONL, and a config-free `status` view of who is healthy right now.
 
@@ -34,7 +39,7 @@ The net effect for us has been **10-100x reduction** in per-task cost for the at
 
 ### LLM-consensus — the multi-model panel, made trivial
 
-Ask several distinct LLMs the same thing and pick the majority answer — an ensemble of frontier models routinely beats any single one. This pattern shows up as [LLM-as-a-Judge](https://arxiv.org/abs/2306.05685) benchmarks, "LLM Council" experiments, [self-consistency decoding](https://arxiv.org/abs/2203.11171), and Karpathy's [recurring observation](https://x.com/karpathy) that mixed panels are strong. But it works only if you can (a) reach N different providers cheaply and (b) fan out in parallel. `external-agents` gives you both:
+Ask several distinct LLMs the same thing and pick the majority answer — an ensemble of frontier models routinely beats any single one. This pattern shows up as [karpathy/llm-council](https://github.com/karpathy/llm-council) (Karpathy's own experimental repo — LLM Council answering hard questions collectively), [LLM-as-a-Judge](https://arxiv.org/abs/2306.05685) benchmarks, and [self-consistency decoding](https://arxiv.org/abs/2203.11171). But it works only if you can (a) reach N different providers cheaply and (b) fan out in parallel. `external-agents` gives you both:
 
 ```
 ids  = pick_agents({ n: 3, min_distinct_providers: 3, exclude_ids: [primary] })
@@ -50,9 +55,19 @@ You don't need Mrrlin's gate to use the pattern — the primitives are unopinion
 
 ## Install
 
+### One-command install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/mrrlin-dev/external-agents/main/install.sh | bash
+```
+
+The script (a) `npm i -g`s the package, (b) registers the MCP server with every supported host on your PATH (Claude Code, Codex — missing hosts are skipped, not fatal), then (c) launches the local dashboard so you can paste free-tier API keys inline. Read [`install.sh`](./install.sh) before piping if that flow makes you nervous — it's ~35 lines.
+
+### Manual
+
 ```bash
 npm install -g @mrrlin-dev/external-agents
-external-agents --version
+external-agents init           # opens http://127.0.0.1:4711 in your browser
 ```
 
 Requires Node ≥ 20. Works on macOS and Linux. Windows via WSL.
@@ -223,10 +238,13 @@ Full schema documented in [docs/registry-schema.md](docs/registry-schema.md).
 ## Local UI — setting up API keys the easy way
 
 ```bash
-external-agents ui
-# → external-agents ui: http://127.0.0.1:4711
+external-agents init      # launches UI + opens the browser (recommended for first-time setup)
+# or
+external-agents ui        # launches UI only; open http://127.0.0.1:4711 yourself
 ```
 
+![external-agents dashboard walkthrough — banner shows 3 free-tier providers waiting; paste key, click Save, get confirmation](docs/ui-walkthrough.gif)
+
 Loopback dashboard (never exposed to the network). Two things you want it for:
 
 ### 1) Golden banner — sign up + paste key inline
@@ -275,7 +293,6 @@ All three paths write to the same `~/.local/state/external-agents/keys.env` —
 Total time: ~3 minutes. Result: 7 more free-tier agents active in `pick`.
 ```
 
-_(TODO: an animated GIF walkthrough belongs here — see [issue #<TBD>](https://github.com/mrrlin-dev/external-agents/issues) for the recording task.)_
 
 ---
 

package/cli.js

@@ -208,6 +208,35 @@ async function cmdSetCredential(args) {
   }
 }
 
+// `external-agents init` — one-shot setup: launch the UI AND open the default
+// browser to it. Meant for the "just installed the package, what now" moment.
+// The UI process stays foregrounded (Ctrl-C to quit) so the operator can watch
+// key-save events land in stderr.
+function cmdInit(flags) {
+  const port = Number(flags.port) || 4711;
+  const host = String(flags.host || "127.0.0.1");
+  const url  = `http://${host}:${port}/`;
+  const opener =
+    process.platform === "darwin" ? "open" :
+    process.platform === "win32"  ? "cmd" :
+    "xdg-open";
+  const openerArgs = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  // Spawn UI first, then open browser after it starts listening.
+  const uiPath = path.join(path.dirname(new URL(import.meta.url).pathname), "ui.js");
+  const env = { ...process.env, EXTERNAL_AGENTS_UI_PORT: String(port), EXTERNAL_AGENTS_UI_HOST: host };
+  const child = spawn(process.execPath, [uiPath], { stdio: "inherit", env });
+  // Give the UI ~600ms to bind before opening the browser (loopback listen is
+  // usually instantaneous but we do not want the browser to open on a not-yet-
+  // bound port).
+  setTimeout(() => {
+    try { spawn(opener, openerArgs, { stdio: "ignore", detached: true }).unref(); }
+    catch { /* browser open is best-effort; UI is still up on ${url} */ }
+  }, 600);
+  child.on("exit", (code) => process.exit(code ?? 0));
+  process.on("SIGINT",  () => child.kill("SIGINT"));
+  process.on("SIGTERM", () => child.kill("SIGTERM"));
+}
+
 // `external-agents ui` — spawn the loopback dashboard (ui.js) inline so the CLI
 // stays the single entry point. ui.js runs its server at top level and blocks;
 // we spawn it as a child so cli.js does not need to import server-lifecycle code
@@ -234,6 +263,7 @@ switch (subcmd) {
   case "probe":    cmdProbe(args); break;
   case "stats":    cmdStats(flags); break;
   case "ui":       cmdUi(flags); break;
+  case "init":     cmdInit(flags); break;
   case "set-credential": await cmdSetCredential(args); break;
   case "help":
   case "--help":
@@ -245,6 +275,7 @@ switch (subcmd) {
   probe <agent-id>
   stats [--since ISO] [--json]
   ui [--port N] [--host H]        # local dashboard for setting keys + inspecting state (default http://127.0.0.1:4711)
+  init [--port N] [--host H]      # launch UI AND open it in the default browser — the "just installed" one-shot
   set-credential <ENV_NAME> [<value> | -]  # persist a key to ~/.local/state/external-agents/keys.env (0600); '-' or omitted = read from stdin`);
     process.exit(subcmd ? 0 : 2);
   default: die(`unknown subcommand: ${subcmd}`, 2);

package/install.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# @mrrlin-dev/external-agents — one-command installer.
+#
+# What it does:
+#   1. Installs the package globally via `npm i -g @mrrlin-dev/external-agents`.
+#   2. Registers the MCP server with EVERY supported host that is on your PATH
+#      (Claude Code + Codex). Missing hosts are skipped, not fatal.
+#   3. Launches `external-agents init` — brings the local dashboard up on
+#      http://127.0.0.1:4711 and opens it in your default browser so you can
+#      paste API keys for the free-tier providers (Groq, Cerebras, OpenRouter).
+#
+# Usage:
+#   curl -fsSL https://raw.githubusercontent.com/mrrlin-dev/external-agents/main/install.sh | bash
+#
+# The script is idempotent: re-running it upgrades the npm package and re-runs
+# the MCP-registration one-liners (both hosts' `mcp add` is a no-op when the
+# entry already matches). Nothing is deleted, nothing is elevated.
+set -euo pipefail
+
+say()  { printf '\033[1m→\033[0m %s\n' "$*" >&2; }
+ok()   { printf '\033[32m✓\033[0m %s\n' "$*" >&2; }
+warn() { printf '\033[33m!\033[0m %s\n' "$*" >&2; }
+
+# 1) npm install (global)
+if ! command -v npm >/dev/null 2>&1; then
+  printf '\033[31m✗\033[0m npm is not on PATH. Install Node.js (>=20) first.\n' >&2
+  exit 1
+fi
+
+say "Installing @mrrlin-dev/external-agents globally via npm…"
+npm install -g @mrrlin-dev/external-agents
+ok "Installed. Binaries: external-agents, external-agents-mcp"
+
+# 2) Register the MCP server with every host we can find. Errors are non-fatal
+# because the operator may only use one of them.
+if command -v claude >/dev/null 2>&1; then
+  say "Registering with Claude Code (claude mcp add)…"
+  claude mcp add external-agents external-agents-mcp 2>/dev/null && ok "Claude Code wired." || warn "claude mcp add returned non-zero (already registered? or CLI is too old). Manual: claude mcp add external-agents external-agents-mcp"
+else
+  warn "Claude Code CLI not found on PATH — skipping. Run this yourself later: claude mcp add external-agents external-agents-mcp"
+fi
+
+if command -v codex >/dev/null 2>&1; then
+  say "Registering with Codex CLI (codex mcp add)…"
+  codex mcp add external-agents -- external-agents-mcp 2>/dev/null && ok "Codex CLI wired." || warn "codex mcp add returned non-zero (already registered? or CLI is too old). Manual: codex mcp add external-agents -- external-agents-mcp"
+else
+  warn "Codex CLI not found on PATH — skipping. Run this yourself later: codex mcp add external-agents -- external-agents-mcp"
+fi
+
+# 3) Launch the dashboard. `init` foregrounds the UI process AND opens the
+# browser; the operator hits Ctrl-C when done.
+say "Launching the local dashboard — paste your free-tier API keys inline…"
+say "(Press Ctrl-C to quit the dashboard once you are done.)"
+exec external-agents init

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mrrlin-dev/external-agents",
-  "version": "0.2.10",
-  "description": "One MCP server for every LLM you talk to — direct-API dispatcher across Gemini, DeepSeek, Groq, OpenRouter, Cerebras, and more. Part of mrrlin.com.",
+  "version": "0.3.0",
+  "description": "One MCP server for every LLM you talk to \u2014 direct-API dispatcher across Gemini, DeepSeek, Groq, OpenRouter, Cerebras, and more. Part of mrrlin.com.",
   "type": "module",
   "main": "server.js",
   "bin": {
@@ -11,7 +11,8 @@
   "scripts": {
     "start": "node server.js",
     "ui": "node ui.js",
-    "cli": "node cli.js"
+    "cli": "node cli.js",
+    "postinstall": "node scripts/postinstall-banner.mjs || true"
   },
   "keywords": [
     "mcp",
@@ -49,7 +50,9 @@
     "agents.yaml",
     "docs/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "scripts/",
+    "install.sh"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "latest",

package/scripts/postinstall-banner.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// Prints a short banner on `npm i -g @mrrlin-dev/external-agents` completion.
+// Skipped when npm runs in a CI or non-interactive context so we do not spam
+// build logs. We stay well within npm etiquette — no auto-launch, no network
+// calls, just a hint.
+if (process.env.CI || process.env.npm_config_production === "true") process.exit(0);
+if (!process.stderr.isTTY) process.exit(0);
+
+const G = "\x1b[32m";  // green
+const B = "\x1b[1m";   // bold
+const D = "\x1b[2m";   // dim
+const R = "\x1b[0m";   // reset
+
+process.stderr.write(`
+${G}${B}✓ @mrrlin-dev/external-agents installed.${R}
+
+${B}Next step (one command):${R}  ${G}external-agents init${R}
+  ${D}↳ opens the local dashboard on http://127.0.0.1:4711${R}
+  ${D}↳ paste API keys inline for Groq / Cerebras / OpenRouter (free tiers)${R}
+  ${D}↳ each provider unlocks in ~30 seconds${R}
+
+Wire the MCP server into your primary agent:
+  ${G}claude mcp add external-agents external-agents-mcp${R}
+  ${G}codex  mcp add external-agents -- external-agents-mcp${R}
+
+More at ${B}https://github.com/mrrlin-dev/external-agents${R}
+`);