model-router

日本語版 → README.ja.md

Routes coding tasks to different models based on difficulty. A skill for Claude Code, Codex, and other tools that support the Agent Skills format.

The idea: a typo fix doesn't need your best model. With this skill installed, the agent classifies each task (T0–T3) and hands it to a cheaper model tier when that's enough. Hard tasks still go to the strong models. You work exactly as before; the routing happens on its own, and your plan quota drains slower because trivial work stops burning top-tier tokens.

Requirements

• Claude Code and/or Codex CLI, installed and logged in
• git
• Node.js 18+ (only for the optional consultation script)

Nothing else. No server, no daemon — it's a set of instruction and config files.

Install

git clone https://github.com/Renga154/model-router.git ~/.agents/skills/model-router
bash ~/.agents/skills/model-router/install/install.sh

The first command puts the skill in ~/.agents/skills/, the shared path that skill-aware tools read. The script then links the skill for Claude Code and Codex, adds three tier agents to ~/.claude/agents/, and adds three tier profiles to ~/.codex/ (skipped if you don't use Codex). It never overwrites existing files; running it twice is fine.

Takes effect in new sessions only — running sessions won't pick it up.

Claude apps (claude.ai / desktop): zip this folder — excluding .git — and upload it under Settings → Capabilities → Skills. The apps can't switch models per task, so there the rubric only affects how much thinking a task gets.

cd ~/.agents/skills && zip -r model-router.zip model-router -x "model-router/.git/*"

Project-level install

To set this up inside one repository instead of your home directory — useful for sharing with teammates via git:

git clone https://github.com/Renga154/model-router.git /tmp/model-router
bash /tmp/model-router/install/install.sh --project /path/to/your/project

This copies real files (no symlinks) into the project: the skill goes to .agents/skills/model-router/ (read by Codex) and .claude/skills/model-router/ (read by Claude Code), the tier agents to .claude/agents/. Commit them and everyone who clones the project gets the routing. Codex tier profiles stay per-user in ~/.codex. To update later, delete the copied folders and re-run.

How routing works

Tier	Typical tasks	Claude Code	Codex
T0 Lite	typo fixes, renames, boilerplate, file lookups	Haiku / low	small model / low
T1 Standard	scoped bug fixes, small features, tests	Sonnet / medium	mid model / medium
T2 Deep	multi-file changes, hard debugging, performance	Opus / high	large model / xhigh
T3 Frontier	architecture, ambiguous requirements	main session, full depth	your default

Rules baked into the skill:

• unsure → one tier up
• a delegate that's out of its depth replies ESCALATE instead of pushing through; the task is retried one tier higher, once, then the main agent takes over
• anything touching security, auth, or billing goes to T2 minimum
• if you name a model yourself, that wins

Each task ends with a one-line note saying which tier ran it.

Always-on

You don't have to type /model-router each time. Once the skill triggers in a chat, it stays active for that chat. To have it on from the first message of every session, add one line to your global instructions:

~/.claude/CLAUDE.md (Claude Code — create the file if it doesn't exist):

- Before starting any implementation/fix/debugging task, classify its difficulty (T0–T3) with the model-router skill and delegate to the matching tier agent (route-lite / route-std / route-deep). An explicit model choice from the user always wins.

~/.codex/AGENTS.md (Codex):

- Before starting any implementation/fix/debugging task, classify its difficulty (T0–T3) using the model-router skill (~/.agents/skills/model-router/SKILL.md) and route accordingly: switch tiers via /model or delegate with `codex exec --profile lite|std|deep`. An explicit model choice from the user always wins.

Without the line, the skill still triggers when the agent matches a task against its description — just not deterministically.

Billing

Feature	Runs on	Paid by
Claude Code tiers	Anthropic models, your normal Claude Code login	your existing Claude subscription or API key
Codex tiers	OpenAI models, your normal Codex login	your existing ChatGPT subscription or API key
Consultation script (optional)	Kimi / Qwen / DeepSeek via OpenRouter	your own OpenRouter credits, if you set them up

Delegation goes through the same logins you already use, so it consumes the subscription you already pay for — at cheaper tiers than usual. OpenRouter only enters the picture for the optional feature below, and only if you add a key.

Cross-model consultation (optional, BYOK)

scripts/consult.mjs asks a model outside the Claude/OpenAI families (Kimi, Qwen, DeepSeek) for a second opinion on design questions, via OpenRouter.

There is no key in this repo. To use the feature, bring your own:

1. Create a key at openrouter.ai/settings/keys (sk-or-...).

2. Add prepaid credits — a few dollars is plenty; a consultation usually costs under a cent.

3. Put the key in your shell profile (~/.zshrc on macOS), then restart the terminal:

   export OPENROUTER_API_KEY=sk-or-your-key-here

No key → the script prints the request it would have sent and exits cleanly. Everything else in this repo works without it. The key is read from the environment per call and is never written to disk or logged.

echo "What are the pitfalls of this retry design?" | node ~/.agents/skills/model-router/scripts/consult.mjs
node ~/.agents/skills/model-router/scripts/consult.mjs --models qwen   # list model IDs, no key needed

Customizing

The routing policy is one table: references/routing.md. Edit it, plus the files it points to:

• Claude Code tiers: model: / effort: in ~/.claude/agents/route-*.md
• Codex tiers: ~/.codex/lite.config.toml, std.config.toml, deep.config.toml

Codex note: valid model IDs depend on your CLI version and account type. If a profile fails with "model not supported", edit it to a model you have. The error is immediate and free.

Uninstall

rm -f  ~/.claude/skills/model-router          # symlink
rm -rf ~/.agents/skills/model-router          # the cloned repo (directory, so -r is needed)
rm -f  ~/.claude/agents/route-lite.md ~/.claude/agents/route-std.md ~/.claude/agents/route-deep.md
rm -f  ~/.codex/lite.config.toml ~/.codex/std.config.toml ~/.codex/deep.config.toml

For a project-level install, remove the copied folders from the project instead:

rm -rf .agents/skills/model-router .claude/skills/model-router
rm -f  .claude/agents/route-lite.md .claude/agents/route-std.md .claude/agents/route-deep.md

Plus any lines you added to ~/.claude/CLAUDE.md / ~/.codex/AGENTS.md.

FAQ

Does this cost extra? No. Claude/Codex routing stays inside the subscriptions you already have. The only potentially paid part is the OpenRouter consultation, which is opt-in.

Is the key handling safe? The repo ships no keys. The script reads yours from an environment variable at call time and doesn't store or log it. .gitignore blocks .env and *.key as a backstop.

Do cheap models hurt quality? Only genuinely trivial work goes to the small tiers. Anything uncertain gets rounded up, and a struggling delegate escalates automatically.

A task didn't get routed. Description-based triggering isn't deterministic. Add the global one-liner from "Always-on", or type /model-router once at the start of a chat.

Layout

SKILL.md                  # the skill: difficulty rubric + routing procedure
references/routing.md     # tier → model/effort table (single source of truth)
references/platforms.md   # per-platform delegation mechanics
scripts/consult.mjs       # optional OpenRouter consultation (zero-dep, BYOK, dry-runs without a key)
install/install.sh        # idempotent installer
install/agents/           # Claude Code tier agents
install/codex/            # Codex tier profiles

License

MIT