Intelligent model routing for Claude Code - Automatically routes queries to the optimal Claude model (Haiku/Sonnet/Opus) based on complexity, reducing costs by up to 98% without sacrificing quality.
This project fills a gap that no existing tool addresses:
| What Exists | What Claude Router Does |
|---|---|
| Multi-provider routers (OpenRouter, etc.) | Intra-Claude optimization (Haiku/Sonnet/Opus) |
Manual /model switching |
Automatic routing via UserPromptSubmit hook |
| Generic LLM complexity scoring | Coding-task specific pattern recognition |
| External API wrapper approach | Native Claude Code integration using subagents |
- Discovered the right architecture - Researched hooks, MCP, and subagents to find the only viable approach
- Solved the hook integration - UserPromptSubmit hook injects routing context that triggers subagent spawning
- Optimized token overhead - Minimal agent definitions reduced overhead by 70% (from 11.9k to 3.4k tokens)
- Built hybrid classification - Rule-based for speed, LLM fallback for accuracy
When using Claude Code, you're typically on a single model:
- Always Opus? You're overpaying 5x for simple queries
- Always Sonnet? Complex architecture tasks may need deeper reasoning
- Manual switching? Tedious and requires knowing which model fits
Claude Router solves this by automatically analyzing each query and routing it to the most cost-effective model.
| Metric | Value |
|---|---|
| Classification latency | ~0ms (rule-based) or ~100ms (LLM fallback) |
| Classification cost | $0 (rules) or ~$0.001 (Haiku fallback) |
| Subagent token overhead | ~3.4k tokens (optimized) |
| Cost savings (simple queries) | ~98% (Haiku vs Opus) |
| Cost savings (mixed workload) | Est. 50-70% |
Intelligent routing creates a win-win for everyone:
LLM pricing has two components, and you save on both:
| Model | Input (per 1M tokens) | Output (per 1M tokens) |
|---|---|---|
| Haiku | $0.25 | $1.25 |
| Sonnet | $3 | $15 |
| Opus | $15 | $75 |
For a typical query (1K input, 2K output tokens):
- Opus cost: $0.015 + $0.15 = $0.165
- Haiku cost: $0.00025 + $0.0025 = $0.00275
- Your savings: ~98%
Haiku is a much smaller, faster model than Opus. When simple queries are routed to Haiku:
- Less GPU compute required per request
- Lower inference latency (faster responses for you)
- More efficient resource allocation across Anthropic's infrastructure
- Frees up Opus capacity for queries that genuinely need it
- Simple queries get instant answers (Haiku is faster)
- Complex queries get thorough analysis (Opus when needed)
- No manual model switching required
For Claude Pro and Max subscribers, intelligent routing means:
- Extended usage limits - Smaller models use less of your monthly capacity
- Longer sessions - Less context consumed = fewer auto-compacts
- Faster responses - Haiku responds 3-5x faster than Opus
The result: You pay less (or extend your subscription further), Anthropic uses fewer resources, and everyone gets appropriately-powered responses. This is sustainable AI usage.
┌─────────────────────────────────────────────────────────────┐
│ Your Query │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ UserPromptSubmit Hook │ │
│ │ (classify-prompt.py) │ │
│ │ │ │
│ │ 1. Rule-based patterns (instant, free) │ │
│ │ 2. Haiku LLM fallback (for edge cases, ~$0.001) │ │
│ └───────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────┼─────────────┐ │
│ ▼ ▼ ▼ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ fast │ │ standard │ │ deep │ │
│ │ (Haiku) │ │ (Sonnet) │ │ (Opus) │ │
│ │ $0.25 │ │ $3 │ │ $15 │ per 1M input │
│ └───────────┘ └───────────┘ └───────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
Note: Choose only ONE installation method. If switching between methods, uninstall the previous one first to avoid conflicts.
Run these commands in any Claude Code session:
# Step 1: Add the marketplace (one-time, per project)
/plugin marketplace add 0xrdan/claude-router
# Step 2: Install the plugin
/plugin install claude-router@claude-router-marketplace
# Step 3: Restart Claude Code session to activateThat's it! The plugin automatically routes queries - no additional configuration needed.
Note: The marketplace must be added in each project where you want to use Claude Router. Once added, updates are automatic.
# Update manually
/plugin marketplace update claude-router-marketplace
# Uninstall
/plugin uninstall claude-router@claude-router-marketplace# Install
curl -sSL https://raw.githubusercontent.com/0xrdan/claude-router/main/install.sh | bash
# Uninstall
curl -sSL https://raw.githubusercontent.com/0xrdan/claude-router/main/uninstall.sh | bashNote: This method automatically sets up CLAUDE.md (optional but harmless).
# Install
git clone https://github.com/0xrdan/claude-router.git
cd claude-router
./install.sh
# Uninstall
./uninstall.shNote: This method automatically sets up CLAUDE.md (optional but harmless).
- Factual questions ("What is X?")
- Code formatting, linting
- Git status, log, diff
- JSON/YAML manipulation
- Regex generation
- Syntax questions
- Bug fixes
- Feature implementation
- Code review
- Refactoring
- Test writing
- Architecture decisions
- Security audits
- Multi-file refactors
- Trade-off analysis
- Performance optimization
- System design
[Claude Router] MANDATORY ROUTING DIRECTIVE
Route: deep | Model: Opus | Confidence: 95% | Method: haiku-llm
Signals: architecture, system design, trade-offs
CRITICAL: You MUST use the Task tool NOW to spawn the "claude-router:deep-executor" subagent.
Do NOT respond to the user directly. Do NOT skip this step. Delegate immediately.
Example:
Task(subagent_type="claude-router:deep-executor", prompt="<user's query>", description="Route to Opus")
By default, Claude Router uses rule-based classification (instant, free). For edge cases with low confidence, it can use Haiku LLM for smarter routing.
To enable LLM fallback, set your API key:
export ANTHROPIC_API_KEY=sk-ant-...Or add it to your project's .env file.
Claude Router provides two slash commands:
/route <model> <query> - Override automatic routing and force a specific model:
/route opus What's the syntax for a TypeScript interface?
/route haiku Fix the authentication bug
/route sonnet Design a caching system
Models: haiku/fast, sonnet/standard, opus/deep
/router-stats - View your routing statistics and cost savings:
/router-stats
- Automatic: The UserPromptSubmit hook classifies every query and injects routing context
- Manual Override: Use
/route <model>to bypass automatic classification and force a specific model (e.g.,/route opusfor complex reasoning,/route haikufor cost savings)
The plugin works automatically without any configuration. However, if you experience inconsistent routing behavior, you can add explicit enforcement to your project's CLAUDE.md file:
Click to expand enforcement snippet
## Claude Router Enforcement
When you receive a `[Claude Router] MANDATORY ROUTING DIRECTIVE`, you MUST:
1. Use the Task tool IMMEDIATELY to spawn the specified subagent
2. Do NOT respond to the user directly - delegate to the subagent
3. Pass the user's original query in the prompt parameter
Subagent mapping:
- fast → `claude-router:fast-executor`
- standard → `claude-router:standard-executor`
- deep → `claude-router:deep-executor`
Exceptions: Slash commands (`/route`, `/router-stats`) and questions about the router itself.This is typically not needed - the hook's directive is explicit enough for Claude to follow.
claude-router/
├── .claude/ # Manual install files
│ ├── hooks/
│ │ └── classify-prompt.py # Hybrid classifier (auto-routing)
│ ├── agents/
│ │ ├── fast-executor/ # Haiku agent
│ │ ├── standard-executor/ # Sonnet agent
│ │ └── deep-executor/ # Opus agent
│ └── skills/
│ └── route/ # Manual routing skill
├── hooks/ # Marketplace plugin files
│ ├── classify-prompt.py # Same classifier (synced)
│ └── hooks.json # Plugin hook config
├── install.sh # Installation script
└── uninstall.sh # Uninstallation script
- Validates their model lineup - Proves Haiku/Sonnet/Opus tiering works in practice
- Real usage data - What % of coding queries actually need Opus?
- Adoption driver - Lower effective cost → more Claude Code usage
- Reference implementation - Could inform native routing features
- Community showcase - Open source tool built for their ecosystem
- Zero-config start - Works immediately with sensible defaults
- Visible savings - Use
/router-statsto see your cost savings - Trust through transparency - Every routing decision is explained
- Easy override -
/route <model>to force any model when needed - Learns from feedback - Future: adjust routing based on user overrides
- Phase 1: Rule-based classification (~0ms, $0)
- Phase 2: Hybrid classification (rules + Haiku LLM fallback)
- Phase 3: Standalone repository
- Phase 4: Usage statistics and plugin distribution
/router-statscommand with multiple value metrics/route <model>command for manual model override- Plugin marketplace distribution
- Subscriber benefits (extended limits, longer sessions)
-
Phase 5: Context-aware routing
- Cache classifications for similar queries
- Factor in number of files open
- Consider session history and error patterns
- Adjust based on project complexity profile
-
Phase 6: Learning from feedback
- Track user overrides
- Adjust future routing based on patterns
- Per-project routing profiles
Contributions are welcome! See CONTRIBUTING.md for guidelines.
git clone https://github.com/0xrdan/claude-router.git
cd claude-router
./install.sh # Choose option 1 for project installMIT License - see LICENSE for details.
Built for the Claude Code community | Report Issues | Follow @dannymonteiro on LinkedIn