model-orchestrator

# 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. A lane is an AI tool or model that can receive work; a tier describes model strength and cost. It sits above the request layer: your agent reads the rules and picks the lane. Request-level proxies and gateways can carry API calls underneath it.

Install: `npx model-orchestrator`. Interactive installation applies the main agent's catalog-supported project rules and settings with backups under one confirmation. Use `--no-apply` or the edit screen to keep activation manual. Headless: `npx model-orchestrator --yes --level 2 --ais claude-code,codex --project . --dir ./ai-orchestrator`. Headless activation requires `--apply-snippets`; add `--dry-run` to preview. Every non-dry install runs a local CLI presence health check; live canaries require `--doctor --run` explicitly. "What's left for you" lists only remaining actions, including one paste step for a chat app.

Companions default to none, including with `--yes`. With activation enabled, supported project MCP configuration is merged with backups; global configuration stays manual. The installer prints third-party setup commands and never runs installs or login flows. Codex's reliable status check removes an already-completed sign-in from the list; other CLIs receive conditional sign-in instructions. Uninstall removes unchanged recorded activation blocks and added hook or MCP entries while preserving surrounding content and backups.

Command: `npm install -g model-orchestrator` makes `aunx` available. `aunx` alone runs the installer; `aunx cli-run` runs an AI CLI; `aunx route-metrics --summary` shows local routing activity; `aunx brief`, `aunx context` and `aunx checks` scaffold task context and verification. `aunx checks run ACCEPTANCE_CHECKS.json` executes trusted check commands and exits 1 on any failure. `aunx route "rename this file"` prints an explained suggestion without launching a worker.

Pick a model proxy (LiteLLM, Portkey, OpenRouter, claude-code-router) for per-request model routing underneath an agent; pick model-orchestrator for task delegation using installed rules, subagents, hooks and a CLI runner. They compose.

## Docs

- [Start here](https://github.com/aunysillyme/model-orchestrator/blob/main/README.md): model routing, activation, commands, search-phrased FAQ and related projects
- [Install and upgrade](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/install.md): flags, walkthrough, 0.1.x upgrades, project commands and uninstall
- [How routing works](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/how-it-routes.md): role, complexity, stakes, model and effort, independent verification
- [Guarantees](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/guarantees.md): code-enforced properties, vendor permissions and agent instructions
- [Optional companions](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/companions.md): other authors' tools, upstream setup and support, fallback tools
- [Beginner](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/part-1-beginner.md): model tiers, a task brief, a context file and acceptance checks inside one agent
- [Intermediate](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/part-2-intermediate.md): subscription lanes, pay-per-token lanes, research and shared work
- [Advanced](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/part-3-advanced.md): Linux host, gateway templates, scheduled work and privacy boundaries
- [Catalog](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/catalog.md): supported AIs, install commands, sign-in and detection

## Reference

- [Commands](https://github.com/aunysillyme/model-orchestrator/blob/main/bin/README.md): aunx subcommands, CLI runner exit codes and output contracts
- [Templates](https://github.com/aunysillyme/model-orchestrator/blob/main/templates/README.md): routing rules, task brief, context, acceptance checks and protocols
- [Claude Code plugin](https://github.com/aunysillyme/model-orchestrator/blob/main/plugin/README.md): installing read-only routing hooks and subagents through the plugin marketplace
- [Proof](https://github.com/aunysillyme/model-orchestrator/blob/main/proof/README.md): dated measurements, methods, sample sizes, expiry and reproduction scripts
- [Security review history](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/security-review-history.md): completed review rounds, incident summaries and regression evidence
- [Catalog advisory checks](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/catalog-advisories.md): package and container inventory, coverage, report statuses, exceptions and manual verification
- [Changelog](https://github.com/aunysillyme/model-orchestrator/blob/main/CHANGELOG.md): release changes and upgrade notes
- [Agent instructions](https://github.com/aunysillyme/model-orchestrator/blob/main/AGENTS.md): headless setup and contributor checks

## Optional

- [Security policy](https://github.com/aunysillyme/model-orchestrator/blob/main/SECURITY.md): private vulnerability reporting
- [agent-personalizer](https://github.com/aunysillyme/agent-personalizer): one interview writes the profile and rules every AI reads, kept in sync from one source
- [website-build-skill](https://github.com/aunysillyme/website-build-skill): current website-building expertise for your AI, from research and design through accessibility and security