{"id":"87670671-daaa-488c-b814-daa24f067013","slug":"modelscout","kind":"skill","name":"modelscout","summary":"Knows which AI models you actually have, picks the right one for every task, routes it to a best-fit subagent, and proves what that saved. One open Agent Skills plugin for Claude Code, Codex, ChatGPT,","owner":"iknowterry","repoUrl":"https://github.com/iknowterry/modelscout","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-07-09T10:36:06.000Z","addedAt":"2026-11-08T07:14:40.286Z","logoUrl":"https://avatars.githubusercontent.com/u/4714377?u=454206c5a9c665069dabacaa2bcf81176e6a43bf&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","productivity"],"tags":["cost-optimization","token-optimization","ai-agents","claude-code","llm","model-selection","openrouter","chatgpt"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-11-08T07:14:57.416Z","sample":false,"url":"https://conduits.dev/tools/modelscout","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"![\"ModelScout](\"plugins/modelscout/assets/icon.svg\")
\n\n# ModelScout π\n\n**Stop paying frontier-model prices for find-and-replace work.**\n**On a subscription? Stop burning your usage limits on it.**\n\nEvery AI subscription and API key you own has a lineup of models behind it β\nand most people run everything on the biggest one. That's like taking a truck\nto buy coffee. Whatever you pay with, the spread is not small:\n\n- **API users** pay in dollars β the price gap between tiers is 5β10Γ.\n- **Subscribers** (Claude Max/Pro, ChatGPT Plus, Gemini Advanced) pay in\n **quota**: every frontier-model request burns your rate limit ~5Γ faster than\n an economy model doing the same job. Tier-right routing is the difference\n between coding until midnight and hitting the \"you've reached your limit\"\n wall at 4pm.\n\n| The task | What most people use | What it needed | Price gap |\n|---|---|---|---|\n| Rename a variable across files | Opus-class ($5/$25 per 1M) | Haiku-class ($1/$5) | **~5Γ** |\n| Summarize a doc | GPT frontier | A mini/flash model | **~10Γ** |\n| Actually-hard debugging | ...the big one. Correctly. | The big one | 1Γ β and ModelScout will say so |\n\n**ModelScout knows which models *you* actually have, picks the right one for\nevery task, and proves what that saved, across every agent you use.**\n\nIt's an open [Agent Skills](https://agentskills.io) plugin. On every task, it\nanswers the question you'd otherwise guess at:\n\n> *\"Which model should I use for this?\"*\n\nThen it acts on the answer: it hands the task to a subagent on that model and\nchecks the result.\n\n**Works in:** Claude Code Β· Codex Β· the ChatGPT desktop app Β· Gemini CLI Β·\nHermes Agent Β· claude.ai. It's one package, installed with each host's own plugin command.\n\n## Why it's different\n\nModel routers exist. Most silently swap the model on every request, from a\nfixed list someone configured. ModelScout is built on three things they don't\ncombine:\n\n- π **Grounded in what you actually have.** One read-only call per provider\n (Anthropic, OpenAI, Gemini, OpenRouter), or your declared subscriptions,\n defines exactly which models are available to you. Prices and capabilities\n come live from the open [models.dev](https://models.dev) catalog. New models\n show up with no update, and it never recommends a model you can't use.\n- π **Proof, not estimates.** `modelscout: savings` measures the *subagents'\n own* token usage from real logs. Routers that only read the main session\n miss exactly the tokens that moved. It's cost-weighted, and it names the\n price behind every number. For subscribers, the % saved is quota freed.\n- π **One brain, every agent.** The same skill, settings and card work in\n Claude Code, Codex, ChatGPT desktop, Gemini CLI, Hermes and claude.ai. Other\n routers each serve a single host.\n\nAnd on every task:\n\n- π **It teaches you the pattern.** The card names the tier and the reason:\n \"T1 mechanical edit, no reasoning needed, so Haiku clears it.\" After a few\n weeks you'll tier tasks yourself.\n- β‘ **It acts, then checks.** It starts a subagent on the best-fit model, and\n your main model verifies the result before reporting.\n- π¦ **It knows when NOT to cheap out.** It routes *up* for hard work, and\n when unsure it biases up. A failed cheap run costs more than the right model\n the first time.\n- β³ **Your rate limits last longer.** Mechanical work on light models leaves\n your frontier-model quota for the work that needs it.\n\n**No API keys needed for subscribers.** Declare what you have once (\"Claude\nMax + ChatGPT Plus\") and ModelScout advises from that β savings framed in what\nyou actually spend: **tokens and rate-limit headroom**, not dollars.\n\n```\ninventory β classify β recommend\n(what you (what the (cheapest model that\n have) task needs) clears the bar β and why)\n```\n\n## What you'll actually see\n\n**You don't have to ask.** Every time you start a new task, ModelScout shows a\nsmall card: what kind of task it is, which model fits it best and why, and\nthen it **just gets on with it**, handing the work to a subagent running that\nmodel:\n\n> **You:** rename `organizerId` to `ownerId` across the codebase and fix imports\n>\n> **Claude:**\n>\n> > `π ModelScout` **T1 mechanical** Β· rename a field across files\\\n> > Best fit: `Haiku` β pattern edits need no deep reasoning Β· ~1/5 of Opus quota\\\n> > β β‘ Routing to a `Haiku` subagent\n>\n> β¦β 43 files updated, verified, imports compile.\n\nIt works in both directions. Ask a Haiku session to debug a race condition and\nthe card says *Best fit: Opus* and routes the work **up** to an Opus subagent.\nWhen your current model already fits, the card is one line:\n> `π ModelScout` **T3 hard reasoning** Β· `Opus` fits β doing it here\n\nand the work continues. Your main session stays on its model, ready\nfor the next hard thing.\n\n### Choose how it behaves: switch, ask, or stay\n\n| Mode | On a mismatch ModelScoutβ¦ | Set it with |\n|---|---|---|\n| **auto** (default) | routes the task to a best-fit subagent straight away | `modelscout: auto` |\n| **ask** | pops up a choice first (below) | `modelscout: ask` |\n| **inform** | shows the card and stays on your current model | `modelscout: inform` |\n| **off** | stays silent | `modelscout: off` |\n\nIn **ask** mode you get a real popup, and your answer can become the default:\n\n> ββ **ModelScout: T1 mechanical task β pattern edits. Who should do it?** ββ\n> β βΈ Run in a Haiku subagent (Recommended) β\n> β βΈ Stay on Opus 5.5 β\n> β βΈ Always use a Haiku subagent for T1 tasks β\n> β βΈ Always stay for T1 tasks β\n> ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\n\n**Per-tier defaults** override the mode, for example \"auto-route everything,\nbut always ask me on T3 work\":\n\n```text\nmodelscout: auto\nmodelscout: T3 ask\n```\n\nTyping `modelscout: β¦` changes the setting instantly. It's handled by the hook,\nso it costs no model turn. `modelscout: status` shows your settings,\n`modelscout: reset` restores the defaults, and **`/modelscout:prefs`** opens\nthe same settings as a popup.\n\n**Guardrails.** Routed work is always verified by your main model before it\nreports back, and redone if it's weak. Destructive or outward-facing steps\n(push, deploy, delete, send) and 1β2 step jobs stay on your main session.\nFollow-ups like \"yes\" or \"continue\" never trigger a card.\n\n## How much does it save? Measured, not guessed\n\nType `modelscout: savings` (or ask *\"how much has ModelScout saved me?\"*).\nThe calculator reads your Claude Code session logs and Hermes Agent's session\ndatabase (read-only) and measures every task ModelScout routed. It reports:\n- **Tokens** handled by the lighter model, counted once per API message\n- **Percentage saved** versus running the same tokens on your main model.\n It's cost-weighted, so cheap cache reads don't inflate it. For subscribers,\n this is the share of usage-limit quota freed.\n- **Main-model budget freed,** in tokens\n- **Time:** measured subagent run time. No invented speed-up claims.\n\nExample output (illustrative numbers):\n\n```text\nπ ModelScout savings β last 30 days\nRouted down to lighter models: 12 task(s), 3.1M tokens, 41.0 min of subagent time\n Saved: 76% of what the main model would have used (β $4.20 at API prices)\n Main-model budget freed: β 2.4M tokens' worth\n```\n\n**A real sample.** The author's machine over 120 days, counting every\nlighter-model subagent (`savings.py --days 120 --all`). Routing was done by\nhand or by other tools before v0.3.0 added the ModelScout marker.\n\n| Measured over 120 days (n = 68 routed tasks) | Value |\n|---|---|\n| Tokens handled by lighter models | 47.6M |\n| Saved vs. the main model | **76%** ($53 at API prices) |\n| Main-model budget freed | β 36.4M tokens |\n| Routes | SonnetβHaiku Γ26 Β· FableβSonnet Γ28 Β· FableβHaiku Γ9 Β· OpusβHaiku Γ1 |\n\nAssumes the main model would have used the same number of tokens. Prices come\nfrom the models.dev catalog, falling back to the newest same-family price,\nand the report names every price it used. One person's workload is an\nexample, not a benchmark.\n\n## How to invoke it β prompts that work\n\n**Most of the time you don't.** The card appears on every new task by itself.\nFor questions *about* models, these phrasings trigger the full advisor:\n\n| You want | Say (any language works) |\n|---|---|\n| A recommendation for a task | *\"Which model should I use to [task]?\"* Β· *\"Is Opus overkill for this?\"* |\n| The budget angle | *\"What's the cheapest model that can [task]?\"* |\n| Help with limits | *\"I keep hitting my usage limit\"* Β· *\"my quota runs out by 4pm\"* |\n| See your inventory | *\"What models do I have access to?\"* Β· *\"Refresh my model inventory\"* |\n| **Guaranteed trigger** | Start with the name: *\"**ModelScout**, which model for this refactor?\"* |\n\n## Quickstart\n\n### Claude Code (plugin β richest experience)\n\n```bash\nclaude plugin marketplace add iknowterry/modelscout\n```\n\n```bash\nclaude plugin install modelscout@modelscout\n```\n\nRestart Claude Code. You get the per-task card with auto-routing, the\n`/modelscout:prefs` settings popup and the full advisor skill. No settings\nedits are needed: the hooks register themselves. To update later, run\n`claude plugin marketplace update modelscout`, then\n`claude plugin update modelscout@modelscout`.\n\nManual install (no plugin system)
\n\n```bash\ngit clone https://github.com/iknowterry/modelscout ~/modelscout\ncp -r ~/modelscout/plugins/modelscout/skills/modelscout ~/.claude/skills/\n```\n\nThen add the per-task hook to `~/.claude/settings.json`:\n\n```json\n{\n \"hooks\": {\n \"UserPromptSubmit\": [\n { \"hooks\": [ { \"type\": \"command\",\n \"command\": \"bash \\\"$HOME/modelscout/plugins/modelscout/hooks/proactive-check.sh\\\" --host=claude\" } ] }\n ]\n }\n}\n```\nSkill only, or the older shell hook
\n\n- **Skill only:** `hermes skills install iknowterry/modelscout/plugins/modelscout/skills/modelscout`\n- **Shell hook:** the plugin replaces it. On older Hermes versions, add this to `~/.hermes/config.yaml`:\n ```yaml\n hooks:\n pre_llm_call:\n - command: \"~/modelscout/plugins/modelscout/hooks/proactive-check.sh\"\n ```\n