Skip to content
Back to search

claude-model-router-hook

Claude Code hooks that auto-switch model tier based on task complexity

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tzachbon--claude-model-router-hook/badge.svg)](/listings/tzachbon--claude-model-router-hook)

HTML

<a href="/listings/tzachbon--claude-model-router-hook"><img src="/api/listings/tzachbon--claude-model-router-hook/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

installer="$(curl -fsSL https://raw.githubusercontent.com/tzachbon/claude-model-router-hook/361031c9381fd6d2b5c47b311b7037015b3c2f6d/install.sh)" && bash -c "$installer"

The wizard asks whether to install globally and star the GitHub repository. Both prompts default to yes. Installation requires Claude Code and Python 3; starring requires an authenticated `gh` command. Restart Claude Code after installation.

<video src="docs/slides/public/model-router.mov" width="887" controls></video>

Claude Model Router classifies each prompt by task and effort, then recommends the matching Claude model. It warns by default. Autoswitch is opt-in and only affects new sessions.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 23 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "claude-model-router-hook",
  4. "owner": {
  5. "name": "tzachbon"
  6. },
  7. "metadata": {
  8. "description": "Automatic model switching for Claude Code based on prompt complexity"
  9. },
  10. "plugins": [
  11. {
  12. "name": "claude-model-router-hook",
  13. "description": "Automatic model switching for Claude Code based on prompt complexity. No API key required.",
  14. "version": "2.1.0",
  15. "author": {
  16. "name": "tzachbon"
  17. },
  18. "source": "./plugins/claude-model-router-hook",
  19. "category": "automation",
  20. "tags": ["model", "routing", "hooks", "automation", "cost-optimization"]
  21. }
  22. ]
  23. }
README.md · README · 122 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # Claude Model Router Hook
  3. **Effort-first model routing for Claude Code. Heuristics-first, opt-in autoswitch.**
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  5. ![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey)
  6. ![Shell](https://img.shields.io/badge/shell-bash-blue)
  7. </div>
  8. ## Install
  9. ```bash
  10. installer="$(curl -fsSL https://raw.githubusercontent.com/tzachbon/claude-model-router-hook/361031c9381fd6d2b5c47b311b7037015b3c2f6d/install.sh)" && bash -c "$installer"
  11. ```
  12. The wizard asks whether to install globally and star the GitHub repository. Both prompts default to yes. Installation requires Claude Code and Python 3; starring requires an authenticated `gh` command. Restart Claude Code after installation.
  13. <video src="docs/slides/public/model-router.mov" width="887" controls></video>
  14. Claude Model Router classifies each prompt by task and effort, then recommends the matching Claude model. It warns by default. Autoswitch is opt-in and only affects new sessions.
  15. ## What it does
  16. - Routes prompts with local heuristics and an optional Claude Code fallback.
  17. - Uses Haiku only for clearly mechanical work; defaults agentic coding to Opus with graduated effort.
  18. - Routes `Agent` and `Task` sub-agents when they spawn. Nested delegation is floored at the implementation target, and an explicit model always wins.
  19. - Records the requested and resolved model for completed sub-agents, so host-side fallback or allowlist substitutions are visible.
  20. - Dampens borderline classifications instead of switching tiers on weak evidence.
  21. ## How it works
  22. | Hook | Job |
  23. |---|---|
  24. | `UserPromptSubmit` | Classifies the prompt and warns or writes the next-session model. |
  25. | `PreToolUse` | Routes `Agent` and `Task` spawns. |
  26. | `PostToolUse` | Logs the model actually used by completed `Agent` and `Task` work. |
  27. | `SessionStart` | Adds the shared task-class rules to each session. |
  28. Errors fail open and leave the prompt unchanged. Prefix a prompt with `~` or `<` to skip routing.
  29. ![Sub-agent spawned with the routed model](assets/sub-agent-routing.png)
  30. <!-- advisory:start -->
  31. ## Model Tier Rules
  32. These rules apply to YOU and to every sub-agent you spawn.
  33. ### Task classes and default targets
  34. | Class | Target model | Effort | When to use |
  35. |---|---|---|---|
  36. | mechanical | haiku | none | Git ops, renames, formatting, lint, file moves, version bumps, quick lookups, short imperative tasks. |
  37. | implementation | opus | medium | Writing or editing code, building features, creating components or APIs, writing tests, standard feature work. |
  38. | debugging | opus | high | Diagnosing failures, flaky tests, races, regressions, stack traces, bisecting, reproducing bugs. |
  39. | architecture | opus | xhigh | Architecture decisions, tradeoff analysis, redesigns, deep multi-file analysis, sustained reasoning over large context. |
  40. | extreme | opus | max | Multi-system migrations, codebase-wide rewrites, long-horizon plans, RFCs and design docs, platform-scale work. |
  41. | abstain | (no routing) | - | Prompt does not clearly match any class; current model and effort pass through unmodified. |
  42. ### Sub-agent model selection (MANDATORY)
  43. When calling the Agent tool, set the model parameter to match the task class
  44. above. Do not default every sub-agent to the highest effort. Match the model
  45. and effort to the work: mechanical work goes to haiku, implementation to opus,
  46. debugging to opus, deep analysis to opus, and platform-scale work to opus.
  47. <!-- advisory:end -->
  48. ## Configure
  49. Use `~/.claude/model-router.json` globally or `.claude/model-router.json` in one project. Project settings win.
  50. ```json
  51. {
  52. "version": 2,
  53. "apply_mode": "warn",
  54. "allow_fable_autoswitch": false,
  55. "subagent_enforcement": "on",
  56. "classifier": { "cli_fallback": true },
  57. "thresholds": { "effort_warn_distance": 2 }
  58. }
  59. ```
  60. | Key | Default | Effect |
  61. |---|---|---|
  62. | `apply_mode` | `warn` | Warn or write the model for the next session. |
  63. | `allow_fable_autoswitch` | `false` | Allow autoswitching to an explicitly configured `fable` target. |
  64. | `subagent_enforcement` | `on` | Route, advise, or ignore sub-agent spawns. |
  65. | `classifier.cli_fallback` | `true` | Use `claude -p --model haiku` for ambiguous prompts. |
  66. | `thresholds.effort_warn_distance` | `2` | Warn near a class boundary. |
  67. <details>
  68. <summary>Alternative installs</summary>
  69. ### Claude plugin manager
  70. ```bash
  71. claude plugin marketplace add tzachbon/claude-model-router-hook
  72. claude plugin install claude-model-router-hook@claude-model-router-hook
  73. ```
  74. ### Manual
  75. ```bash
  76. git clone https://github.com/tzachbon/claude-model-router-hook.git
  77. cd claude-model-router-hook
  78. ./plugins/claude-model-router-hook/install.sh
  79. ```
  80. The manual installer prints the `settings.json` entries that you need to add.
  81. </details>
  82. ## Notes
  83. - Activity is logged at `~/.claude/hooks/model-router-hook.log`, including requested versus resolved sub-agent models.
  84. - If another `PreToolUse` hook rewrites the same spawn, Claude Code's undocumented merge order decides which rewrite wins.
  85. ## Project
  86. [Contributing](CONTRIBUTING.md) | [MIT license](LICENSE) | Based on [model-matchmaker](https://github.com/coyvalyss1/model-matchmaker) by [@coyvalyss1](https://github.com/coyvalyss1)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.