Claude Code Router

Enhanced Claude Code router with robust process management, graceful shutdown, and health monitoring capabilities.

Features

🚀 Enhanced Process Management

• Robust PID file handling with file locking
• Graceful shutdown with connection draining
• Automatic cleanup and recovery

📊 Health Monitoring

• Built-in health check endpoints (/health, /ready, /alive)
• Production-ready monitoring integration
• Process metrics and status reporting

🔧 Production Deployment

• PM2 ecosystem configuration included
• Systemd service file for Linux servers
• Docker-ready setup

🛡️ Reliability

• Zero data loss during restarts
• Configurable shutdown timeouts
• Automatic resource cleanup

Installation

# Install globally
npm install -g @tehreet/claude-code-router

# Or install locally
npm install @tehreet/claude-code-router

Quick Start

1. Create configuration file at ~/.claude-code-router/config.json:

{
  "Providers": [
    {
      "name": "gemini",
      "api_base_url": "https://generativelanguage.googleapis.com/v1beta/models/",
      "api_key": "YOUR_API_KEY",
      "models": ["gemini-2.5-flash", "gemini-2.5-pro"],
      "transformer": {
        "use": ["gemini"]
      }
    }
  ],
  "Router": {
    "default": "gemini,gemini-2.5-flash"
  }
}

2. Start the service:

ccr start

3. Check status:

ccr status

4. Test health endpoint:

curl http://localhost:3456/health

Commands

ccr start          # Start the service
ccr stop           # Stop the service gracefully  
ccr status         # Show service status
ccr code "prompt"  # Execute code command
ccr --help         # Show help information

Health Endpoints

• GET /health - Basic health status
• GET /ready - Readiness probe (K8s compatible)
• GET /alive - Liveness probe with metrics

Example response:

{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "uptime": 3600,
  "pid": 12345
}

Production Deployment

PM2 (Recommended)

# Install PM2
npm install -g pm2

# Start with PM2 using included config
pm2 start ecosystem.config.js

# Save PM2 state
pm2 save && pm2 startup

Systemd (Linux)

# Install as system service
sudo ./scripts/install-systemd.sh

# Manage with systemctl
sudo systemctl start claude-code-router
sudo systemctl status claude-code-router

Docker

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist ./dist
EXPOSE 3456
CMD ["npm", "start"]

Configuration

Supported Providers

• OpenRouter - Multiple model access
• Gemini - Google's Gemini models
• DeepSeek - DeepSeek models with tool use
• Ollama - Local model serving
• VolcEngine - Enterprise AI platform

Environment Variables

• SERVICE_PORT - Port to run on (default: 3456)
• NODE_ENV - Environment (development/production)
• CONFIG_PATH - Custom config file path

Monitoring Integration

Prometheus

scrape_configs:
  - job_name: 'claude-code-router'
    static_configs:
      - targets: ['localhost:3456']
    metrics_path: '/health'

Kubernetes

livenessProbe:
  httpGet:
    path: /alive
    port: 3456
  initialDelaySeconds: 10

readinessProbe:
  httpGet:
    path: /ready
    port: 3456
  initialDelaySeconds: 5

API Usage

Send requests to the router exactly like the Claude API:

curl -X POST http://localhost:3456/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [
      {"role": "user", "content": "Hello, world!"}
    ]
  }'

Troubleshooting

Service Won't Start

# Check if port is in use
lsof -i :3456

# Check PID file
cat ~/.claude-code-router/.claude-code-router.pid

# View logs (PM2)
pm2 logs claude-code-router

Health Check Fails

# Test endpoints
curl http://localhost:3456/health
curl http://localhost:3456/ready
curl http://localhost:3456/alive

# Check service status
ccr status

Development

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

# Install dependencies
npm install

# Build project
npm run build

# Start development server
npm start

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Issues
• 💬 Discussions

Changelog

v2.0.0

• ✅ Enhanced process management with file locking
• ✅ Graceful shutdown with connection draining
• ✅ Health monitoring endpoints
• ✅ PM2 and systemd integration
• ✅ Production deployment configurations