smart-router-marketplace

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

1. Smart Router Skill - On first use, scans your plugins and builds a registry
2. Smart Caching - Registry cached using hash-based invalidation (rebuilds only when plugins change)
3. 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:

1. Check if registry exists - If .claude/.cache/agent-registry.json doesn't exist → build it
2. Hash-based cache invalidation - Compute hash of plugin mtimes, compare to cached hash
3. Rebuild if needed - Only rebuilds when plugins changed (added/updated/removed)
4. 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)
5. Extract capabilities from descriptions using keyword matching
6. 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