Smart Router
Plugin discovery and context-aware routing system for Claude Code.
Overview
Smart Router solves the problem of having many installed plugins without knowing which one to use. It automatically discovers all your installed plugins (21+ in most setups) and intelligently routes you to the best tool based on your task context and preferences.
Problem It Solves
When you have multiple plugins installed:
- 3+ code review agents - Which one should you use?
- Multiple brainstorming skills - Which fits your task?
- Various testing tools - What's best for this situation?
Without Smart Router, Claude Code may not consistently use your installed tools, or you have to manually remember and select them each time.
How It Works
- Smart Router Skill - On first use, scans your plugins and builds a registry
- Smart Caching - Registry cached using hash-based invalidation (rebuilds only when plugins change)
- Context-Aware Routing - Ranks options by context, specialty, and user preferences
Features
- ✅ Auto-discovery - Scans
~/.claude/plugins/ and .claude/commands/
- ✅ Smart caching - Hash-based invalidation, rebuilds only when plugins change
- ✅ Context-aware - Routes based on file types, project structure
- ✅ User preferences - Auto-route, show menu, or context-based (configurable)
- ✅ Lightweight - Fast registry lookup, minimal overhead
Installation
From Marketplace (Recommended)
Step 1: Add the marketplace
/plugin marketplace add Blockchain-Oracle/smart-router
Step 2: Install the plugin
/plugin install smart-router@smart-router-marketplace
That's it! Smart Router is now active and will automatically discover your plugins on the next session.
Alternative: Direct Git Clone
# Clone directly to your global plugins directory
git clone https://github.com/Blockchain-Oracle/smart-router ~/.claude/plugins/smart-router
Local Development
# Test locally before installing
cd /path/to/smart-router
claude --plugin-dir .
Configuration
Quick Setup (Recommended)
Use the interactive configuration command:
/smart-router:configure
This will guide you through setting up your preferences with questions and validation.
Manual Setup
Alternatively, create .claude/smart-router.local.md manually:
---
routingMode: auto # auto | ask | context
showReasoning: true # Show why tool was chosen
excludePlugins: # Plugins to ignore
- plugin-name
priorityOrder: # Override default ranking
- superpowers
- pr-review-toolkit
---
Routing Modes
auto - Automatically picks best tool, no questions asked (fastest)ask - Shows menu of options, lets you choose (most control)context - Uses file context to decide automatically (balanced, recommended)
Usage
Automatic Routing
Just work normally! Smart Router runs in the background:
You: "I need a code review"
→ Smart Router detects need
→ Auto-routes to best code review tool
→ Review happens seamlessly
Configuration Setup
Set up your routing preferences interactively:
/smart-router:configure
Guides you through:
- Routing mode selection (auto/ask/context)
- Display preferences (show reasoning)
- Priority order (preferred plugins)
- Exclusions (plugins to ignore)
Manual Registry Rebuild
Force rebuild the plugin registry:
/smart-router:rebuild
Useful after:
- Installing new plugins
- Updating existing plugins
- Debugging routing issues
How Registry Works
Build Process (On-Demand)
The registry is built automatically when the Smart Router skill is invoked:
- Check if registry exists - If
.claude/.cache/agent-registry.json doesn't exist → build it
- Hash-based cache invalidation - Compute hash of plugin mtimes, compare to cached hash
- Rebuild if needed - Only rebuilds when plugins changed (added/updated/removed)
- Scan sources:
~/.claude/plugins/cache/ for installed plugins.claude/commands/ for local commands (e.g., BMAD workflows)~/.claude.json for global MCPs- Plugin-provided MCPs (from plugin.json mcpServers field)
- Extract capabilities from descriptions using keyword matching
- Write registry to
.claude/.cache/agent-registry.json
Performance: Registry builds in <3 seconds, cached for entire session
Registry Format
{
"version": "1.0",
"lastBuilt": "2025-12-19T12:00:00Z",
"hash": "abc123...",
"capabilities": {
"code-review": [
{
"plugin": "superpowers",
"type": "skill",
"entry": "skills/code-reviewer/SKILL.md",
"description": "General code review with TDD focus"
}
]
}
}
Ranking Logic