model-orchestrator
Model router for AI coding agents: installs routing rules, 8 subagents, hooks and a CLI runner so your AI picks model and effort per task and saves tokens.
Routine work can use a cheap model. Planning and difficult decisions can use a stronger one. Your agent gets editable rules for making that choice and a runner that checks whether delegated work returned a result.
A lane is one AI tool or model your agent can hand work to. A tier describes a model's strength and cost: planning model, working model or cheap model.
npx model-orchestrator
What the model router gives you
| Part | What you get |
|---|---|
| Routing rules | A decision tree for bulk work, reading, live data, review, verification, planning and builds |
| Subagents and hooks | Named jobs with explicit tools, plus routing reminders inside Claude Code |
| Step-by-step playbooks (protocols) | A build process from acceptance checks through independent review and verified use |
| Task brief and context file | One shared set of facts, plus each worker's scope, permissions and checks |
| Lane runner | Honest exit codes, optional file or JSON checks, requested model and effort recorded per run |
| Routing metrics | Your local routing split and subagent activity |
The package sits above the request layer: your agent reads the rules and picks the lane. Request-level proxies and gateways can carry the API calls underneath it. aunx route prints a deterministic suggestion for your agent to consider.
For agents: llms.txt links the reference docs; AGENTS.md gives headless commands.
Preview a setup:
npx model-orchestrator --yes --level 2 --ais claude-code,codex --primary claude-code --project . --dir ./ai-orchestrator --dry
After you install
The interactive installer applies the main agent's project rules and, for Claude Code, merges its hooks. The summary names these changes before the single confirmation; existing files get timestamped backups. A local health check runs automatically after installation.
- What's left for you: follow the remaining sign-in or setup steps printed at the end. Codex sign-in is listed only when its reliable status check cannot confirm it; other CLIs get an "if you have not signed in yet" instruction. A chat-app main agent keeps one paste step. A CLI main agent with no cataloged project rules file (for example Grok or Hermes) gets a "load the block" instruction instead of a file to copy.
- Your agent: start a fresh session in the project.
ai-orchestrator/README.md(or the README in your chosen--dir) explains the installed rules and activation check. - Control: use
--no-applyor the edit screen to keep activation manual. Headless--yeskeeps project rules and settings untouched unless you add--apply-snippets. Use--dryto preview.
Selected companions get project-scoped registration where the host supports it; global configuration remains a printed step. The health check checks CLI presence and sends no prompt. Live checks remain opt-in with aunx cli-run --doctor --run. Installation and upgrades cover every flag.
Install the command once to use the shorter forms below:
npm install -g model-orchestrator
aunx --help
aunx without a subcommand runs the same installer as model-orchestrator. The installer writes its files and the project activation changes shown in the summary. Every companion is opt-in, including with --yes; missing tools appear together under Install these yourself, with official commands and links.
Part of a set
| Repo | What it gives you |
|---|---|
| agent-personalizer | One interview writes the profile and rules every AI you use reads, kept in sync from one source. |
| model-orchestrator | Model router for AI coding agents: installs routing rules, 8 subagents, hooks and a CLI runner so your AI picks model and effort per task and saves tokens |
| website-build-skill | A skill pack that teaches your AI current website-building expertise: research, design, code, accessibility, performance, search and security. |
Model routing and request-level proxies
An HTTP proxy or gateway such as LiteLLM, Portkey, OpenRouter or claude-code-router swaps the model per request underneath the agent. model-orchestrator is an installer that writes routing rules, subagents, hooks and a lane runner above the request layer.
- Pick a proxy for request-level model routing and a shared API entry point.
- Pick model-orchestrator for task delegation across your agents, model tiers and CLIs.
They compose: your agent follows the installed rules, and a proxy can route its API requests underneath.
Choose the setup that fits your tools
| Level | Your setup | What it adds |
|---|---|---|
| Beginner | One agent or chat app | Task classification, model tiers, a task brief, acceptance checks and build protocols |
| Intermediate | Several AI CLIs | A lane runner, delegation matrix, research triage and model/effort flags |
| Advanced | An always-on Linux machine | Gateway templates, privacy rules and a scheduled review job |
Read beginner, intermediate or advanced.
Works with the AIs you already pay for
The installer detects your AI tools, shows the proposed setup and asks Write these files? with [Y/n/e]. Confirm once, or enter e to change a setting. With no detected tools, select the AIs you have first. The main agent receives its supported agent set; at level 2 and up, selected CLIs supported by the runner become worker lanes.
| AI | Installer ID | What it is and gives |
|---|---|---|
| Claude Code | claude-code |
Anthropic's terminal agent; project rules, subagents and routing hooks when main |
| Codex | codex |
OpenAI's terminal agent; read-only filesystem sandbox for --audit, project rules when main |
| Antigravity | agy |
Google's terminal agent; project rules and custom agents when main |
| Grok | grok |
xAI's terminal agent on a subscription |
| Hermes | hermes |
A free terminal agent using the providers you authenticate |
| Qwen Code | qwen |
A terminal agent using your provider key; project rules when main |
| Ollama | ollama |
A model runtime that runs on your machine |
| Claude, ChatGPT and Gemini apps | claude-app, chatgpt-app, gemini-app |
PASTE-INTO-YOUR-AGENT.md: a routing block for your chat app |
Every install includes Your stack: who does what: planning, building, independent review, verification, research, bulk work, reading and private work, plus fan-out and long-context roles when supported. One deterministic assignment uses the selected tools' capabilities, billing and selection order. Independent review requires a known different model family; private work requires a local runtime. Unavailable roles are stated explicitly.
Subagent definitions name planning, working or cheap model tiers. Your plan and tool configuration select the actual models. MANIFEST.json stores the assignment, and aunx route reads it even when you keep edited routing documents. How assignment works.
npx model-orchestrator --list prints supported IDs and setup notes. The catalog lists installation, sign-in and detection details.
Lane runner (aunx cli-run)
Run from your project. aunx cli-run uses the package runner; pass --dir to use a project's installed runner. Replace <lane> below with a CLI lane from your generated stack table.
aunx cli-run --doctor
aunx cli-run '<lane>' --brief TASK_BRIEF.md
# Direct form from the installed rules folder:
node bin/cli-run.mjs '<lane>' --brief TASK_BRIEF.md
--doctor --run sends a small live check through your own vendor sign-ins. Each run records the requested model and effort and a fixed result class in a local log. A missing result returns nonzero. Add --expect-file or --expect-json when success needs a concrete output contract. Runner reference.
Task brief (aunx brief) and acceptance checks (aunx checks)
aunx context CONTEXT.md
aunx brief new TASK_BRIEF.md
aunx checks ACCEPTANCE_CHECKS.json
aunx checks run ACCEPTANCE_CHECKS.json
Fill the context file with verified facts, quote the user's ask in the brief, and give every requirement a check command. The check runner reports PASS or FAIL and exits 1 when a check fails. Run only check files you trust: their commands execute with your shell's permissions. See the acceptance-check protocol.
Routing suggestions (aunx route)
aunx route "rename this file"
aunx route "design the auth system"
The first suggests cheap bulk work; the second suggests planning. Each prints the AI assigned to that role in your installation. Use --dir PATH for a custom rules folder; otherwise it reads ./ai-orchestrator/MANIFEST.json, then ./MANIFEST.json. With no install, it prints a generic suggestion and an install notice. The classifier uses keywords and points unmatched requests to ROUTING.md. It reads JSON and launches no worker.
See where your agent sends work (aunx route-metrics)
aunx route-metrics --summary
aunx route-metrics --summary --since 2026-09-01
On Claude Code installs, the routing hook records turns, route markers and subagent activity locally. The summary reports your routing split, route-marker coverage and agent durations. Prompt text and the explanation inside a route marker never enter that log. Measured results and reproduction scripts show dated figures with methods and sample sizes; expired entries fail the test suite.
Claude Code plugin
/plugin marketplace add aunysillyme/model-orchestrator
/plugin install model-orchestrator@model-orchestrator
The plugin carries read-only routing hooks and the subagents. Generate your project's routing rules with npx model-orchestrator. The npm installer also supplies the local metrics hook. Plugin setup.
Works well with
These are other authors' projects, maintained in their own repositories. All companions start unselected. Choosing one writes guidance and configuration snippets. With activation enabled, supported project configuration is merged automatically; you install the tool and complete any printed setup steps yourself.
| Project | Author | What it adds |
|---|---|---|
| codecalc | The-40-Thieves | Local calculation, code execution and logic checks |
| obsidian-tc | The-40-Thieves | Searchable notes and controlled writes over an Obsidian vault |
| Context7 | Upstash | Current, version-specific library documentation |
Use --tools codecalc,obsidian-tc,context7 to select them. Without a companion, use your available calculator or runtime, a searchable notes folder and official library docs. Companion setup and upstream support.
Common questions
What is a model router for coding agents?
It helps an agent match a task to a model, effort level and toolset. Run npx model-orchestrator to install editable rules, subagents and a CLI runner for your setup; your agent makes the routing decision.
How do I use Claude Code and Codex together?
Run npx model-orchestrator --yes --level 2 --ais claude-code,codex --primary claude-code --project . --dir ./ai-orchestrator, then follow the activation summary. Claude Code can dispatch scoped work through aunx cli-run codex --brief TASK_BRIEF.md and use a different model family for review.
How do I reduce Claude Code token usage?
Install routing rules with npx model-orchestrator, so your agent has guidance for sending routine work to cheaper models and keeping reads scoped. Use aunx route-metrics --summary to measure where your work goes; savings depend on your tasks and model choices.
How do I route tasks to cheaper models?
Use aunx route "rename this file" for a keyword-based suggestion, then apply your installed ORCHESTRATOR.md at level 1, or ROUTING.md and TIERS.md at level 2 and up, to the actual task. Role selects the job, complexity sets effort, and the consequences of a mistake affect the model and reviewer.
How does this work with an AI gateway or LLM router?
It coordinates multi-agent work at task level; a proxy such as LiteLLM or OpenRouter can route the API requests underneath it. npx model-orchestrator --level 3 includes gateway templates when you want that setup.
How does an agent install and run it headlessly?
Pass --yes --level 2 --ais claude-code,codex --project . --dir ./ai-orchestrator to npx model-orchestrator; add --dry-run to preview. Existing edits are preserved by default, and --update-docs refreshes files whose installed hashes still match.
Uninstall
Run npx model-orchestrator --uninstall --dir ./ai-orchestrator --project . (add --dry to preview). The installer removes unedited managed files, its recorded activation block and the hook entries it added, preserving surrounding rules and settings. It names edited or manually pasted entries that need your attention; backups stay. Removal details.
Read next
- Install and upgrade: flags, folders, walkthrough and safe reruns.
- How routing works: model, effort and independent verification.
- Guarantees: executable checks and agent instructions.
- Proof: dated measurements and scripts you can rerun.
- Security review history: findings, fixes and regression evidence.
Platform support, and every test this suite skips
Node 18 or newer, with zero runtime dependencies. Works on macOS and Linux; the level 3 box templates assume Ubuntu. Windows: CI runs the suite on windows-latest (Node 18, 20, 22), including lane execution end to end through cli-run against a fake CLI installed the same way npm installs a real one (a .cmd shim). cli-run never runs a lane through cmd.exe: it resolves the shim to the Node script underneath and spawns Node directly, so a prompt reaching a real lane never passes through a Windows shell. A .cmd or .bat lane that cannot be resolved that way (an old or hand-edited shim) is refused with exit 13 and a message saying how to fix it, rather than run through cmd.exe: a batch file re-reads its arguments after cmd.exe has parsed them once, and no escaping fully contains a prompt through both passes. Install, detection, the hooks and cli-run's taskkill tree kill are tested on Windows too, including SIGTERM/SIGINT to the wrapper (Windows has no OS-level signals: both terminate it unconditionally, verified there rather than treated the same as POSIX). The Windows skip list covers POSIX behavior, with each skip pinned by test/prose.test.js: statSync().mode's executable bit (NTFS has none, so that one assertion is conditional inside a test that otherwise runs everywhere); a lane dying mid-run from a real POSIX signal (a real Windows lane cannot die "by signal"); running weekly-audit.sh's watchdog functions for real under Git Bash's job control, both the end-to-end run and the bounded() timeout check (the script itself only ever runs on the Ubuntu box it targets); and a mkfifo FIFO at the rules path, the one case that proves route-gate.mjs cannot HANG on a non-regular file, since Windows has no mkfifo to build one (the guard behind it is covered on every OS by a directory at the same path); and an untracked mkfifo FIFO in the repository cli-run --audit sizes, the case that proves --effort auto never opens a non-regular file (the symlink half of that test runs on every OS). test/prose.test.js counts every skip: in the suite and requires this list to document each one.
Additional security regressions skip Windows for the project-hook symlink and manifest FIFO fixtures and the symlinked-manifest refusal message (symlink privileges and POSIX special files), the POSIX shell descendant timeout fixture (the argv equivalent still runs on Windows), and four weekly credential and report lifecycle runtime checks (the Ubuntu watchdog requires POSIX process-tree semantics). Their configuration and generated syntax remain covered on every platform.
Privacy. The installer sends no telemetry and makes no network call of its own once it is running. Two things around that are worth being exact about:
npx model-orchestratoris itself a download: npm fetches this package from the registry before any of it runs.npm install -g model-orchestratoronce, then runmodel-orchestrator, if you would rather that happen exactly one time.- Every missing vendor CLI or selected companion is listed under Install these yourself, with an official command and link. The installer runs no third-party installs.
--no-installremains accepted for existing scripts.
cli-run calls the vendor CLI you name.
Vendor version compatibility
Detection checks whether a binary is present. Use the compatibility table below to compare vendor versions. --doctor reports presence; add --run to send a small canary to every enabled worker and check its sign-in and output against the runner's success criteria.
The lane wiring and the output judges were written against these versions, which are the ones this release was exercised on:
| Lane | Vendor | Version this release was built against | Where that number is proved |
|---|---|---|---|
claude |
Anthropic | 2.1.226 | the npm pin the installer writes, @anthropic-ai/claude-code@2.1.226 |
codex |
OpenAI | 0.153.4 | test/fixtures/codex-0.153.4.jsonl, a recorded run |
agy |
1.1.27 | test/fixtures/agy-1.1.27.jsonl, a recorded run |
|
grok |
xAI | 1.0.5 | test/fixtures/grok-1.0.5.json, a recorded run |
hermes |
Nous Research | 0.20.0 | test/fixtures/hermes-0.20.0.txt, a recorded run |
qwen |
Alibaba | 0.22.3 | test/fixtures/qwen-0.22.3-nokey.json, a recorded run |
ollama |
Ollama | 0.33.3 | the pinned image the level 3 box runs, ollama/ollama:0.33.3 |
Generated from src/catalog.js by npm run gen:catalog; npm test fails if this table and the catalog disagree. Fixtures were captured 2026-09-06.
For npm-installed lanes, builtAgainst in the catalog supplies both the compatibility table and the install pin. Newer vendor versions may work or may change a flag the generated wiring uses. When a lane starts failing after a vendor upgrade, compare against this table first.
The live canary runs on your machine, with your credentials. That is what aunx cli-run --doctor --run (direct form: node bin/cli-run.mjs --doctor --run) is: it sends every enabled lane one tiny prompt through your own sign-ins and reports canary ok or canary FAILED rc= per lane. Choose this optional live check after setup or a vendor upgrade when you want to verify actual responses.
CI runs the full suite against stub lanes on Ubuntu, macOS and Windows, Node 18/20/22, plus a packaged install into a clean consumer. Run the live check locally to verify your own sign-ins, quota and vendor versions.
Contributing
Contributions are welcome:
- New AIs: add an entry to
src/catalog.js; prompts, tables, configs and docs use the catalog. - Vendor updates: contribute a lane fixture captured from a newer vendor version and the test that checks it.
- Docs: fix an unclear instruction or add a reproducible example.
Run npm test with your change. Keep templates free of logic and credential values. See CONTRIBUTING.md, RELEASING.md and SECURITY.md.
Credits
- @shawnwows reviewed the router and made the case for separating role, complexity and stakes instead of compressing them into one scale, for recording the model and effort a lane was actually asked for, and for verifying findings before they trigger repairs. All three shipped in 0.1.14.