Claude Code Router

📋 Copy All Commands 📄 Generate PDF

Comprehensive Claude Code Router commands and workflows for routing Claude Code requests to different AI models, enabling multi-model development and cost optimization.

Overview

Claude Code Router is an open-source tool that acts as a local proxy for Claude Code requests, allowing you to intercept, modify, and route requests to different AI models including GPT-4, Gemini, local models, and other OpenAI-compatible APIs. This enables developers to use Claude Code's powerful interface while leveraging different models for specific tasks, cost optimization, or accessing free API credits.

⚠️ Usage Notice: Claude Code Router modifies API requests and requires proper configuration of API keys and endpoints. Always ensure secure handling of credentials and compliance with API terms of service.

Installation

Quick Setup

# Install via npm
npm install -g claude-code-router

# Install via pip
pip install claude-code-router

# Clone from GitHub
git clone https://github.com/musistudio/claude-code-router.git
cd claude-code-router
npm install

Docker Installation

# Pull Docker image
docker pull claudecode/router:latest

# Run with Docker
docker run -p 8080:8080 -e OPENAI_API_KEY=your-key claudecode/router

# Docker Compose
version: '3.8'
services:
  claude-router:
    image: claudecode/router:latest
    ports:
      - "8080:8080"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}

Build from Source

# Clone repository
git clone https://github.com/musistudio/claude-code-router.git
cd claude-code-router

# Install dependencies
npm install

# Build project
npm run build

# Start router
npm start

Configuration

Basic Configuration

{
  "router": {
    "port": 8080,
    "host": "localhost",
    "logLevel": "info",
    "enableCors": true
  },
  "models": {
    "claude-3-sonnet": {
      "provider": "anthropic",
      "apiKey": "${ANTHROPIC_API_KEY}",
      "endpoint": "https://api.anthropic.com/v1/messages"
    },
    "gpt-4": {
      "provider": "openai",
      "apiKey": "${OPENAI_API_KEY}",
      "endpoint": "https://api.openai.com/v1/chat/completions"
    },
    "gemini-pro": {
      "provider": "google",
      "apiKey": "${GOOGLE_API_KEY}",
      "endpoint": "https://generativelanguage.googleapis.com/v1/models"
    }
  },
  "routing": {
    "defaultModel": "claude-3-sonnet",
    "fallbackModel": "gpt-4",
    "loadBalancing": false,
    "costOptimization": true
  }
}

Advanced Routing Rules

{
  "routingRules": [
    {
      "name": "code_generation",
      "condition": {
        "messageContains": ["write code", "implement", "create function"],
        "fileTypes": [".py", ".js", ".ts", ".java"]
      },
      "targetModel": "gpt-4",
      "priority": 1
    },
    {
      "name": "documentation",
      "condition": {
        "messageContains": ["document", "explain", "comment"],
        "taskType": "documentation"
      },
      "targetModel": "claude-3-sonnet",
      "priority": 2
    },
    {
      "name": "cost_optimization",
      "condition": {
        "tokenCount": { "max": 1000 },
        "complexity": "low"
      },
      "targetModel": "gpt-3.5-turbo",
      "priority": 3
    }
  ]
}

Core Commands

Router Management

Command	Description
router start	Start the Claude Code Router
router stop	Stop the router service
router restart	Restart the router
router status	Check router status
router config	View current configuration
router logs	View router logs
router health	Health check endpoint

Model Management

Command	Description
router models list	List available models
router models add	Add new model configuration
router models remove	Remove model configuration
router models test	Test model connectivity
router models switch	Switch default model
router models status	Check model status

Claude Code Integration

Configure Claude Code

# Set Claude Code to use router
export ANTHROPIC_API_BASE=http://localhost:8080/v1
export ANTHROPIC_API_KEY=router-proxy-key

# Alternative configuration
claude-code config set api.base_url http://localhost:8080/v1
claude-code config set api.key router-proxy-key

# Verify configuration
claude-code config show

Router Proxy Setup

# Start router with specific configuration
claude-code-router --config config.json --port 8080

# Start with environment variables
ROUTER_PORT=8080 ROUTER_CONFIG=config.json claude-code-router

# Start with custom models
claude-code-router --models gpt-4,claude-3-sonnet,gemini-pro

Model Providers

OpenAI Integration

{
  "openai": {
    "apiKey": "${OPENAI_API_KEY}",
    "baseUrl": "https://api.openai.com/v1",
    "models": {
      "gpt-4": {
        "maxTokens": 8192,
        "temperature": 0.7,
        "costPerToken": 0.00003
      },
      "gpt-3.5-turbo": {
        "maxTokens": 4096,
        "temperature": 0.7,
        "costPerToken": 0.000002
      }
    }
  }
}

Google Gemini Integration

{
  "google": {
    "apiKey": "${GOOGLE_API_KEY}",
    "baseUrl": "https://generativelanguage.googleapis.com/v1",
    "models": {
      "gemini-pro": {
        "maxTokens": 32768,
        "temperature": 0.7,
        "costPerToken": 0.000001
      },
      "gemini-pro-vision": {
        "maxTokens": 16384,
        "temperature": 0.7,
        "supportsImages": true
      }
    }
  }
}

Local Model Integration

{
  "local": {
    "baseUrl": "http://localhost:11434/v1",
    "models": {
      "llama2": {
        "endpoint": "/api/generate",
        "maxTokens": 4096,
        "temperature": 0.7,
        "costPerToken": 0
      },
      "codellama": {
        "endpoint": "/api/generate",
        "maxTokens": 8192,
        "temperature": 0.3,
        "specialization": "code"
      }
    }
  }
}

OpenRouter Integration

{
  "openrouter": {
    "apiKey": "${OPENROUTER_API_KEY}",
    "baseUrl": "https://openrouter.ai/api/v1",
    "models": {
      "anthropic/claude-3-sonnet": {
        "maxTokens": 200000,
        "costPerToken": 0.000015
      },
      "openai/gpt-4": {
        "maxTokens": 8192,
        "costPerToken": 0.00003
      },
      "google/gemini-pro": {
        "maxTokens": 32768,
        "costPerToken": 0.000001
      }
    }
  }
}

Routing Strategies

Load Balancing

{
  "loadBalancing": {
    "enabled": true,
    "strategy": "round_robin",
    "models": ["gpt-4", "claude-3-sonnet", "gemini-pro"],
    "weights": {
      "gpt-4": 0.4,
      "claude-3-sonnet": 0.4,
      "gemini-pro": 0.2
    },
    "healthCheck": {
      "enabled": true,
      "interval": 60,
      "timeout": 10
    }
  }
}

Cost Optimization

{
  "costOptimization": {
    "enabled": true,
    "budget": {
      "daily": 10.00,
      "monthly": 300.00,
      "currency": "USD"
    },
    "rules": [
      {
        "condition": "tokenCount < 500",
        "model": "gpt-3.5-turbo"
      },
      {
        "condition": "tokenCount >= 500 && tokenCount < 2000",
        "model": "claude-3-haiku"
      },
      {
        "condition": "tokenCount >= 2000",
        "model": "claude-3-sonnet"
      }
    ]
  }
}

Intelligent Routing

{
  "intelligentRouting": {
    "enabled": true,
    "rules": [
      {
        "name": "code_tasks",
        "patterns": ["implement", "write code", "debug", "refactor"],
        "model": "gpt-4",
        "confidence": 0.8
      },
      {
        "name": "analysis_tasks",
        "patterns": ["analyze", "explain", "review", "understand"],
        "model": "claude-3-sonnet",
        "confidence": 0.9
      },
      {
        "name": "creative_tasks",
        "patterns": ["create", "design", "brainstorm", "generate"],
        "model": "gemini-pro",
        "confidence": 0.7
      }
    ]
  }
}

Monitoring and Analytics

Usage Tracking

# View usage statistics
curl http://localhost:8080/api/stats

# Model usage breakdown
curl http://localhost:8080/api/stats/models

# Cost analysis
curl http://localhost:8080/api/stats/costs

# Performance metrics
curl http://localhost:8080/api/stats/performance

Logging Configuration

{
  "logging": {
    "level": "info",
    "format": "json",
    "outputs": ["console", "file"],
    "file": {
      "path": "./logs/router.log",
      "maxSize": "100MB",
      "maxFiles": 10,
      "compress": true
    },
    "metrics": {
      "enabled": true,
      "interval": 60,
      "endpoint": "/metrics"
    }
  }
}

Health Monitoring

# Health check endpoint
curl http://localhost:8080/health

# Detailed health status
curl http://localhost:8080/health/detailed

# Model availability
curl http://localhost:8080/health/models

# Performance metrics
curl http://localhost:8080/metrics

Advanced Features

Request Transformation

// Custom request transformer
const requestTransformer = {
  transform: (request, targetModel) => {
    // Modify request based on target model
    if (targetModel === 'gpt-4') {
      request.temperature = 0.3; // Lower temperature for code
    } else if (targetModel === 'claude-3-sonnet') {
      request.max_tokens = 4096; // Adjust token limit
    }
    return request;
  }
};

// Response transformer
const responseTransformer = {
  transform: (response, sourceModel) => {
    // Standardize response format
    return {
      content: response.content || response.message,
      model: sourceModel,
      usage: response.usage,
      timestamp: new Date().toISOString()
    };
  }
};

Plugin System

// Router plugin interface
class RouterPlugin {
  constructor(config) {
    this.config = config;
  }

  onRequest(request, context) {
    // Pre-process request
    return request;
  }

  onResponse(response, context) {
    // Post-process response
    return response;
  }

  onError(error, context) {
    // Handle errors
    console.error('Router error:', error);
  }
}

// Load plugins
const plugins = [
  new CostTrackingPlugin(),
  new CachePlugin(),
  new RateLimitPlugin()
];

Caching System

{
  "cache": {
    "enabled": true,
    "type": "redis",
    "connection": {
      "host": "localhost",
      "port": 6379,
      "password": "${REDIS_PASSWORD}"
    },
    "ttl": 3600,
    "keyPrefix": "claude-router:",
    "compression": true,
    "rules": [
      {
        "pattern": "explain*",
        "ttl": 7200
      },
      {
        "pattern": "generate*",
        "ttl": 1800
      }
    ]
  }
}

Security and Authentication

API Key Management

{
  "security": {
    "authentication": {
      "enabled": true,
      "type": "bearer",
      "keys": [
        {
          "key": "router-key-1",
          "permissions": ["read", "write"],
          "rateLimit": 1000
        },
        {
          "key": "router-key-2",
          "permissions": ["read"],
          "rateLimit": 100
        }
      ]
    },
    "encryption": {
      "enabled": true,
      "algorithm": "AES-256-GCM",
      "keyRotation": 86400
    }
  }
}

Rate Limiting

{
  "rateLimit": {
    "enabled": true,
    "global": {
      "requests": 1000,
      "window": 3600
    },
    "perKey": {
      "requests": 100,
      "window": 3600
    },
    "perModel": {
      "gpt-4": {
        "requests": 50,
        "window": 3600
      },
      "claude-3-sonnet": {
        "requests": 100,
        "window": 3600
      }
    }
  }
}

Troubleshooting

Common Issues

# Router not starting
- Check port availability
- Verify configuration file
- Check API key validity
- Review log files

# Model connection failures
- Test API endpoints
- Verify API keys
- Check network connectivity
- Review rate limits

# Performance issues
- Monitor memory usage
- Check cache configuration
- Review routing rules
- Optimize model selection

Debug Mode

# Enable debug logging
DEBUG=claude-router:* npm start

# Verbose logging
claude-code-router --log-level debug

# Request tracing
curl -H "X-Debug: true" http://localhost:8080/v1/messages

# Performance profiling
curl http://localhost:8080/debug/profile

Performance Optimization

{
  "performance": {
    "connectionPool": {
      "maxConnections": 100,
      "timeout": 30000,
      "keepAlive": true
    },
    "compression": {
      "enabled": true,
      "level": 6,
      "threshold": 1024
    },
    "clustering": {
      "enabled": true,
      "workers": "auto"
    }
  }
}

Deployment

Production Deployment

# Kubernetes deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: claude-router
spec:
  replicas: 3
  selector:
    matchLabels:
      app: claude-router
  template:
    metadata:
      labels:
        app: claude-router
    spec:
      containers:
      - name: claude-router
        image: claudecode/router:latest
        ports:
        - containerPort: 8080
        env:
        - name: OPENAI_API_KEY
          valueFrom:
            secretKeyRef:
              name: api-keys
              key: openai
        - name: ANTHROPIC_API_KEY
          valueFrom:
            secretKeyRef:
              name: api-keys
              key: anthropic

Docker Compose

version: '3.8'
services:
  claude-router:
    image: claudecode/router:latest
    ports:
      - "8080:8080"
    environment:
      - NODE_ENV=production
      - ROUTER_CONFIG=/app/config/production.json
    volumes:
      - ./config:/app/config
      - ./logs:/app/logs
    restart: unless-stopped

  redis:
    image: redis:alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

volumes:
  redis_data:

Resources

• Claude Code Router GitHub
• Documentation
• Community Discord
• Video Tutorials
• OpenRouter Integration