agent-model-router

A local-first MCP server and TypeScript library that recommend a model and reasoning effort for a delegated coding task. The orchestrator asks for a recommendation and starts its own agent. This server never starts agents.

No API key, inference request, account lookup, telemetry or routing fee. Models, capability ratings, relative cost/speed, availability and policies live in JSON. MIT licensed. Requires Node.js 22 or newer.

How it works

flowchart TB
    Task["Task + context + priority"] --> Orchestrator["Codex orchestrator"]
    Orchestrator --> Tool["MCP tool: select_model"]

    subgraph Router["Local model router · no inference calls"]
        Tool --> Analyze["Classify task and estimate complexity"]
        Analyze --> Rank["Rank available models using the selected policy"]
        Registry[("JSON registry<br/>Models · capabilities · cost · speed<br/>Availability · policies · supported efforts")]
        Registry -.-> Analyze
        Registry -.-> Rank
        Rank --> Effort["Choose a supported reasoning effort"]
        Effort --> Result["Recommendation<br/>Model + effort + confidence + reason"]
    end

    Result --> Supported{"Host supports<br/>the recommended pair?"}
    Supported -- Yes --> Apply["Orchestrator uses the recommended configuration"]
    Supported -- No --> Default["Orchestrator uses its default configuration"]
    Tool -. Routing error .-> Default
    Apply --> Agent["Orchestrator creates the subagent"]
    Default --> Agent

    classDef input fill:#164e63,stroke:#22d3ee,color:#fff,stroke-width:2px;
    classDef routing fill:#312e81,stroke:#a5b4fc,color:#fff,stroke-width:2px;
    classDef config fill:#78350f,stroke:#fbbf24,color:#fff,stroke-width:2px;
    classDef decision fill:#701a75,stroke:#f0abfc,color:#fff,stroke-width:2px;
    classDef result fill:#14532d,stroke:#4ade80,color:#fff,stroke-width:2px;
    classDef fallback fill:#7c2d12,stroke:#fb923c,color:#fff,stroke-width:2px;
    class Task,Orchestrator input;
    class Tool,Analyze,Rank,Effort routing;
    class Registry config;
    class Supported decision;
    class Result,Apply,Agent result;
    class Default fallback;
    style Router fill:#0f172a,stroke:#94a3b8,color:#fff,stroke-width:2px;

Purple: local routing. Amber: configuration. Green: recommendation and orchestrator action. Orange: fallback. Only the orchestrator creates agents.

Related MCP server: TaskGrade MCP Server

Run locally

git clone https://github.com/Intelligent-Intern/agent-model-router.git
cd agent-model-router
npm ci
npm run build
node dist/cli.js select \
  --task "Find potential race conditions in this codebase" \
  --context "TypeScript backend, distributed workers" \
  --priority balanced

The bundled example registry returns:

{
  "model": "gpt-6.1-terra",
  "reasoning_effort": "high",
  "confidence": 0.8128,
  "reason": "Concurrency and distributed-system analysis Complexity 0.70; balanced policy selects gpt-6.1-terra (capability 0.93) with high effort."
}

confidence measures heuristic separation and category evidence. It is not a calibrated success probability. Registry numbers are illustrative weights, not actual prices, latency measurements or benchmark claims.

MCP: select_model

Start the local stdio server:

node dist/cli.js serve
# Or use an explicit, complete registry snapshot:
node dist/cli.js serve --config /absolute/path/router.json

The server reserves stdout for MCP. Startup/CLI errors go to stderr. Invalid configuration exits with a nonzero status; it never silently loads another file. The official MCP TypeScript SDK v2 handles initialization and protocol negotiation, including legacy stdio clients.

Input:

{
  "task": "Find potential race conditions in this codebase",
  "context": "TypeScript backend, distributed workers",
  "priority": "balanced"
}

• task: required nonblank string, at most 20,000 characters.

• context: optional string, at most 40,000 characters; defaults to empty.

• priority: quality, balanced, speed, or cost; defaults to balanced.

• available_models: optional model-ID array supplied by the host. Intersects registry availability. An empty array means no available models.

• Unknown input keys are rejected.

Output has model, reasoning_effort, confidence, and reason, both as MCP structuredContent and JSON text. If no model is available, the tool returns an MCP error rather than fabricating a recommendation. The orchestrator then uses its own default configuration. Invalid arguments are rejected by the MCP SDK.

Codex setup

Merge examples/codex/config.toml into your project's .codex/config.toml, replacing its absolute paths. Copy or merge examples/codex/AGENTS.md into your own instructions. No user-level configuration is modified by this package.

The instructions require routing before authorized delegation and applying the recommendation only through fields the host actually supports. On a host without per-agent overrides, use a configured role or inherit defaults. If routing or an override fails, fall back once to default delegation. The router does not bypass delegation restrictions.

Codex compatibility verification records the live interface inspected, the installed CLI version, supported overrides in that session, and the distinction between tool parameters and config-file settings. See also the official Codex subagent documentation.

CLI

# Pipe a request; CLI flags override the corresponding JSON fields.
printf '%s' '{"task":"Add unit tests","priority":"cost"}' | node dist/cli.js select

# Inspect classification, complexity, every candidate score and fallback warnings.
node dist/cli.js select --task "Review security across services" --explain

# Limit recommendations to the host's known model IDs.
node dist/cli.js select --task "Refactor the parser" \
  --available-models gpt-6.1-sol,gpt-6.1-terra

node dist/cli.js validate --config config/default.json
node dist/cli.js --help
npm run demo

CLI success exits 0. Invalid input/configuration and routing failures exit 1. Input from stdin is bounded to 256 KiB; configuration is bounded to 1 MiB.

Standalone library

The library can be imported without creating an MCP server:

import { HeuristicRouter, loadConfig } from 'agent-model-router';

const router = new HeuristicRouter(await loadConfig());
const recommendation = router.select({
  task: 'Review distributed workers for race conditions',
  priority: 'quality',
});
console.log(recommendation);

const explanation = router.explain({ task: 'Fix a typo in README', priority: 'cost' });
console.log(explanation.analysis, explanation.candidates, explanation.warnings);

For an already-loaded JSON snapshot, use new HeuristicRouter(snapshot). The constructor validates and copies configuration. Each request is independent and deterministic for the same snapshot and input. There is no request history, file watching or implicit registry refresh.

createMcpServer(router) is exported from agent-model-router/mcp. It accepts the ModelRouter interface, including async implementations. The default engine uses replaceable TaskAnalyzer and ModelRanker interfaces. A future remote API, benchmark ranker or hosted registry can use these boundaries without changing MCP or implementing a SaaS backend in this package.

Configure the registry

Copy config/default.json, edit it, then run validate. The configuration is a full replacement, not a partial override. Schema version 1 rejects unknown keys. Referential and policy checks run at load/construction.

Each model declares:

classification defines category descriptions and weighted literal phrases. complexity defines a baseline and weighted signals. Each priority has quality, speed and cost weights, quality floors and effort thresholds. fallback defines a registered model and supported effort.

The sample uses model IDs exposed in the implementation session. Verify them in your own host; they are not universally available. To use another provider, replace the IDs/provider metadata, supported efforts and ratings. No provider API is called. Relative figures influence policy decisions, not billing.

See architecture and scoring for the exact formula, effort mapping, tie-breaking and extension points.

Fallbacks and failure handling

• Unknown category: configured fallback, confidence 0.3, explicit reason.

• No model meets quality/complexity requirements: degraded fallback, explicitly identified in the reason and full explanation.

• Configured fallback unavailable: highest-scoring available model.

• Requested effort unsupported: next supported level up, or highest supported level when no higher level exists. The explanation records the mapping.

• Nothing available: NoModelAvailableError in the library; nonzero CLI exit; MCP tool error. The orchestrator decides whether to inherit its default.

• Invalid configuration: fail startup. Existing router instances retain their validated snapshot and are unaffected by edits to the source file.

Twelve example decisions

These are deterministic outputs from npm run demo with the bundled example registry, not quality benchmarks:

The runnable inputs are in examples/tasks.json.

Development and package verification

npm ci
npm run check      # ESLint, strict TypeScript, build, Node unit/integration tests
npm run demo       # twelve routing decisions
npm pack --dry-run # inspect the publishable artifact, without publishing
npm pack           # create a local tarball; does not publish

Tests cover deterministic ranking, configuration validation, availability, fallbacks, effort support, Unicode boundaries, isolation, CLI errors and real MCP stdio initialization/tool calls. GitHub Actions runs the same checks on Node 22 and 24. No secrets, API key or inference budget are required.

To install a locally built tarball:

npm install ./agent-model-router-0.1.0.tgz
npx --no-install agent-model-router select --task "Add unit tests" --priority cost

The package includes built JS/declarations, registry, documentation, examples and license. Its prepack hook builds TypeScript. There is no automatic release or npm publication workflow.

Limitations and assumptions

• Heuristics match configured phrases, not intent. Negation, quoted instructions, unusual wording, multilingual tasks without matching configured phrases and misleading context can produce poor classifications. Unknown wording falls back. Task text is data; the router executes no instructions from it.

• The engine never inspects the repository, runs benchmarks or checks account entitlements. Its recommendation is only as good as the supplied description, ratings and availability snapshot. It cannot prove a globally optimal choice.

• Relative cost/speed and capability ratings are examples. Effort-specific token costs and latency, rate limits, quotas and live health are not modeled.

• Confidence is uncalibrated. A high value is not a guarantee of correctness.

• The host can ignore or reject a recommendation. An AGENTS.md file guides the orchestrator; it is not a technical enforcement mechanism.

• Reasoning labels and model availability differ across providers and Codex hosts. Configure the registry and inspect the actual delegation tool schema.

• V1 implements local stdio only. HTTP hosting, authentication, billing, analytics, feedback storage, registry downloads and LLM routing are not implemented.

Contributing

Open an issue or pull request with a reproducible routing input, configuration revision and expected behavior. Run npm run check and update the examples when changing policies. Avoid committing private task descriptions or credentials.

License

MIT.