Claude Code Observer

A traffic observer for Claude Code that proxies requests and provides real-time SSE (Server-Sent Events) streaming for monitoring and debugging.

English | 中文

✨ Features

• Traffic Proxy: Proxies Claude Code API requests to different LLM providers (e.g., DeepSeek, OpenAI, etc.)
• Real-time Streaming: SSE-based real-time traffic monitoring and event streaming
• Request/Response Tracking: Captures complete request and response data including headers and timing
• Web Dashboard: Built-in web interface for visualizing traffic streams
• Health Monitoring: Health check endpoint for service monitoring
• Easy Deployment: Docker support with Docker Compose configuration

🚀 Getting Started

Installation

Install the package globally:

npm install -g @musistudio/claude-code-router

Or build from source:

git clone <repository-url>
cd observer-for-claude-code-node
npm install
npm run build

Running the Server

Method 1: Using the CLI

observer

Method 2: Using Node.js

node dist/cli.js

Method 3: Using Docker

docker-compose up

The server will start on port 8080 by default. You can change the port by setting the PORT environment variable:

PORT=3000 node dist/cli.js

📡 API Endpoints

Health Check

Check if the service is running:

curl http://localhost:8080/health

Response:

{
  "status": "OK",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Traffic Proxy

Proxy requests to different LLM providers:

curl http://localhost:8080/proxy/{model}/{path}

• {model}: Base64 encoded target API URL (optional, defaults to DeepSeek)
• {path}: API endpoint path

Example:

curl -X POST http://localhost:8080/proxy/aHR0cHM6Ly9hcGkuZGVlcHNlZWsubmV0L2FudGhyb3BpYw==/v1/messages \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4", "messages": [{"role": "user", "content": "Hello"}]}'

SSE Traffic Stream

Connect to the real-time traffic stream:

curl -N http://localhost:8080/proxy/trace

Event format:

{
  "id": "uuid",
  "type": "REQUEST|RESPONSE",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "body": "request/response body",
  "statusCode": 200,
  "durationMs": 1234
}

🖥️ Web Dashboard

Access the built-in web dashboard at:

http://localhost:8080/

The dashboard provides a real-time view of all traffic flowing through the proxy.

🔧 Configuration

Environment Variables

• PORT: Server port (default: 8080)
• TARGET_URL: Default target API URL (default: https://api.deepseek.com/anthropic)

Building the Project

npm run build

Type Checking

npm run type-check

🐳 Docker Deployment

Using Docker Compose

docker-compose up -d

Using Docker directly

docker build -t claude-code-observer .
docker run -p 8080:8080 claude-code-observer

📝 Use Cases

1. Debugging API Requests: Monitor and debug Claude Code API requests and responses
2. Traffic Analysis: Analyze traffic patterns and performance metrics
3. Multi-Provider Support: Route requests to different LLM providers easily
4. Development: Test Claude Code integrations with various providers

🔒 Security Considerations

• By default, the server listens on all interfaces. In production, consider restricting access
• Use reverse proxies (nginx, Traefik) for additional security features
• Implement authentication if deploying to public networks

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT

🙋 Support

If you encounter any issues or have questions, please open an issue on GitHub.