@tehreet/claude-code-router/README.md

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

# Claude Code Router

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

[![npm version](https://badge.fury.io/js/@tehreet%2Fclaude-code-router.svg)](https://badge.fury.io/js/@tehreet%2Fclaude-code-router)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 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

```bash
# 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`:

```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**:

```bash
ccr start
```

3. **Check status**:

```bash
ccr status
```

4. **Test health endpoint**:

```bash
curl http://localhost:3456/health
```

## Commands

```bash
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:
```json
{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "uptime": 3600,
  "pid": 12345
}
```

## Production Deployment

### PM2 (Recommended)

```bash
# 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)

```bash
# 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

```dockerfile
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

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

### Kubernetes

```yaml
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:

```bash
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
```bash
# 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
```bash
# Test endpoints
curl http://localhost:3456/health
curl http://localhost:3456/ready
curl http://localhost:3456/alive

# Check service status
ccr status
```

## Development

```bash
# 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](LICENSE) file for details.

## Support

- 📖 [Documentation](docs/DEPLOYMENT.md)
- 🐛 [Issues](https://github.com/vibe-coders-only/claude-code-router/issues)
- 💬 [Discussions](https://github.com/vibe-coders-only/claude-code-router/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