npm package: @sumanit/claude-code-observer
Description: Use Claude Code without an Anthropics account and route it to another LLM provider
Author: sumanit
Latest version: 1.0.0

# 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** | [中文](README_zh.md)

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

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

Or build from source:

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

### Running the Server

#### Method 1: Using the CLI

```shell
observer
```

#### Method 2: Using Node.js

```shell
node dist/cli.js
```

#### Method 3: Using Docker

```shell
docker-compose up
```

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

```shell
PORT=3000 node dist/cli.js
```

## 📡 API Endpoints

### Health Check

Check if the service is running:

```shell
curl http://localhost:8080/health
```

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

### Traffic Proxy

Proxy requests to different LLM providers:

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

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

Example:
```shell
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:

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

Event format:
```json
{
  "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

```shell
npm run build
```

### Type Checking

```shell
npm run type-check
```

## 🐳 Docker Deployment

### Using Docker Compose

```shell
docker-compose up -d
```

### Using Docker directly

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