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

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

$3

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

$3

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

$3

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

Configuration

$3

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

$3

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

Monitoring Integration

$3

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

$3

`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

$3


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

$3

`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 file for details.

Support

- 📖 Documentation
- 🐛 Issues
- 💬 Discussions

Changelog

$3

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