Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/ZhangHanDong/claude-code-api-rs

A high-performance Rust implementation of an OpenAI-compatible API gateway for Claude Code CLI.
https://github.com/ZhangHanDong/claude-code-api-rs

Last synced: 3 months ago
JSON representation

A high-performance Rust implementation of an OpenAI-compatible API gateway for Claude Code CLI.

Awesome Lists containing this project

README 

          
# Claude Code API



[![Version](https://img.shields.io/badge/version-0.1.5-blue.svg)](https://github.com/ZhangHanDong/claude-code-api-rs)

[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

[![Rust](https://img.shields.io/badge/rust-1.75+-orange.svg)](https://www.rust-lang.org)



[中文文档](README_CN.md) | English



A high-performance Rust implementation of an OpenAI-compatible API gateway for Claude Code CLI. Built on top of the robust [claude-code-sdk-rs](https://github.com/ZhangHanDong/claude-code-api-rs/tree/main/claude-code-sdk-rs), this project provides a RESTful API interface that allows you to interact with Claude Code using the familiar OpenAI API format.



## ✨ Features



- **🔌 OpenAI API Compatibility** - Drop-in replacement for OpenAI API, works with existing OpenAI client libraries

- **🚀 High Performance** - Built with Rust, Axum, and Tokio for exceptional performance

- **📦 Powered by claude-code-sdk-rs** - Built on a robust SDK with full Claude Code CLI integration

- **⚡ Connection Pooling** - Reuse Claude processes with optimized connection pooling for 5-10x faster responses

- **💬 Conversation Management** - Built-in session support for multi-turn conversations

- **🖼️ Multimodal Support** - Process images alongside text in your requests

- **⚡ Response Caching** - Intelligent caching system to reduce latency and costs

- **🔧 MCP Support** - Model Context Protocol integration for accessing external tools and services

- **📁 File Access Control** - Configurable file system permissions for secure operations

- **🌊 Streaming Responses** - Real-time streaming support for long-form content

- **🛡️ Robust Error Handling** - Comprehensive error handling with automatic retries

- **📊 Statistics API** - Monitor usage and performance metrics

- **🔄 Multiple Client Modes** - OneShot, Interactive, and Batch processing modes



## 🚀 Quick Start



### Prerequisites



- Rust 1.75 or higher

- [Claude CLI](https://claude.ai/download) installed and configured

- (Optional) MCP servers for extended functionality



### Installation



**Option 1: Install from crates.io**



```bash

cargo install claude-code-api

```



Then run:

```bash

RUST_LOG=info claude-code-api

# or use the short alias

RUST_LOG=info ccapi

```



**Option 2: Build from source**



```bash

git clone https://github.com/ZhangHanDong/claude-code-api-rs.git

cd claude-code-api-rs

```



Build the entire workspace (API server + SDK):

```bash

cargo build --release

```



Start the server:

```bash

./target/release/claude-code-api

```



**Note**: The API server automatically includes and uses `claude-code-sdk-rs` for all Claude Code CLI interactions.



The API server will start on `http://localhost:8080` by default.



### Quick Test



```bash

curl -X POST http://localhost:8080/v1/chat/completions \

  -H "Content-Type: application/json" \

  -d '{

    "model": "claude-opus-4-20250514",

    "messages": [

      {"role": "user", "content": "Hello, Claude!"}

    ]

  }'

```



## 📖 Core Features



### 1. OpenAI-Compatible Chat API



```python

import openai



# Configure the client to use Claude Code API

client = openai.OpenAI(

    base_url="http://localhost:8080/v1",

    api_key="not-needed"  # API key is not required

)



response = client.chat.completions.create(

    model="claude-opus-4-20250514",

    messages=[

        {"role": "user", "content": "Write a hello world in Python"}

    ]

)



print(response.choices[0].message.content)

```



### 2. Conversation Management



Maintain context across multiple requests:



```python

# First request - creates a new conversation

response = client.chat.completions.create(

    model="claude-opus-4-20250514",

    messages=[

        {"role": "user", "content": "My name is Alice"}

    ]

)

conversation_id = response.conversation_id



# Subsequent request - continues the conversation

response = client.chat.completions.create(

    model="claude-opus-4-20250514",

    conversation_id=conversation_id,

    messages=[

        {"role": "user", "content": "What's my name?"}

    ]

)

# Claude will remember: "Your name is Alice"

```



### 3. Multimodal Support



Process images with text:



```python

response = client.chat.completions.create(

    model="claude-opus-4-20250514",

    messages=[{

        "role": "user",

        "content": [

            {"type": "text", "text": "What's in this image?"},

            {"type": "image_url", "image_url": {"url": "/path/to/image.png"}}

        ]

    }]

)

```



Supported image formats:

- Local file paths

- HTTP/HTTPS URLs

- Base64 encoded data URLs



### 4. Streaming Responses



```python

stream = client.chat.completions.create(

    model="claude-opus-4-20250514",

    messages=[{"role": "user", "content": "Write a long story"}],

    stream=True

)



for chunk in stream:

    if chunk.choices[0].delta.content:

        print(chunk.choices[0].delta.content, end="")

```



### 5. MCP (Model Context Protocol)



Enable Claude to access external tools and services:



```bash

# Create MCP configuration

cat > mcp_config.json << EOF

{

  "mcpServers": {

    "filesystem": {

      "command": "npx",

      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]

    },

    "github": {

      "command": "npx",

      "args": ["-y", "@modelcontextprotocol/server-github"],

      "env": {

        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"

      }

    }

  }

}

EOF



# Start with MCP support

export CLAUDE_CODE__MCP__ENABLED=true

export CLAUDE_CODE__MCP__CONFIG_FILE="./mcp_config.json"

./target/release/claude-code-api

```



## 🔧 Configuration



### Environment Variables



```bash

# Server configuration

CLAUDE_CODE__SERVER__HOST=0.0.0.0

CLAUDE_CODE__SERVER__PORT=8080



# Claude CLI configuration

CLAUDE_CODE__CLAUDE__COMMAND=claude

CLAUDE_CODE__CLAUDE__TIMEOUT_SECONDS=300

CLAUDE_CODE__CLAUDE__MAX_CONCURRENT_SESSIONS=10

CLAUDE_CODE__CLAUDE__USE_INTERACTIVE_SESSIONS=true



# File access permissions

CLAUDE_CODE__FILE_ACCESS__SKIP_PERMISSIONS=false

CLAUDE_CODE__FILE_ACCESS__ADDITIONAL_DIRS='["/path1", "/path2"]'



# MCP configuration

CLAUDE_CODE__MCP__ENABLED=true

CLAUDE_CODE__MCP__CONFIG_FILE="./mcp_config.json"

CLAUDE_CODE__MCP__STRICT=false

CLAUDE_CODE__MCP__DEBUG=false



# Cache configuration

CLAUDE_CODE__CACHE__ENABLED=true

CLAUDE_CODE__CACHE__MAX_ENTRIES=1000

CLAUDE_CODE__CACHE__TTL_SECONDS=3600



# Conversation management

CLAUDE_CODE__CONVERSATION__MAX_HISTORY_MESSAGES=20

CLAUDE_CODE__CONVERSATION__SESSION_TIMEOUT_MINUTES=30

```



### Configuration File



Create `config/local.toml`:



```toml

[server]

host = "0.0.0.0"

port = 8080



[claude]

command = "claude"

timeout_seconds = 300

max_concurrent_sessions = 10

use_interactive_sessions = false  # Disabled by default due to stability issues



[file_access]

skip_permissions = false

additional_dirs = ["/Users/me/projects", "/tmp"]



[mcp]

enabled = true

config_file = "./mcp_config.json"

strict = false

debug = false

```



## 📦 Built on claude-code-sdk-rs



This API server is built on top of [claude-code-sdk-rs](https://github.com/ZhangHanDong/claude-code-api-rs/tree/main/claude-code-sdk-rs), a powerful Rust SDK for Claude Code CLI that provides:



- **Full Feature Parity** with the official Python SDK

- **Multiple Client Types**: 

  - `query()` - Simple one-shot queries

  - `InteractiveClient` - Stateful conversations with context

  - `OptimizedClient` - Advanced client with connection pooling and performance features

- **Streaming Support** - Real-time message streaming

- **Complete Type Safety** - Strongly typed with serde support

- **Async/Await** - Built on Tokio for high-performance async operations



### Using the SDK Directly



If you prefer to build your own integration, you can use the SDK directly:



```toml

[dependencies]

cc-sdk = "0.1.5"

tokio = { version = "1.0", features = ["full"] }

```



```rust

use cc_sdk::{query, ClaudeCodeOptions, PermissionMode};



#[tokio::main]

async fn main() -> Result<(), Box> {

    // Simple query

    let response = query("Explain quantum computing").await?;

    println!("{}", response);



    // With options

    let options = ClaudeCodeOptions::builder()

        .model("claude-3.5-sonnet")

        .permission_mode(PermissionMode::AcceptAll)

        .build();

    

    let response = cc_sdk::query_with_options("Write a haiku", options).await?;

    println!("{}", response);

    

    Ok(())

}

```



## 📚 API Endpoints



### Chat Completions

- `POST /v1/chat/completions` - Create a chat completion



### Models

- `GET /v1/models` - List available models



### Conversations

- `POST /v1/conversations` - Create a new conversation

- `GET /v1/conversations` - List active conversations

- `GET /v1/conversations/:id` - Get conversation details



### Statistics

- `GET /stats` - Get API usage statistics



### Health Check

- `GET /health` - Check service health



## 🛠️ Advanced Usage



### Using with LangChain



```python

from langchain.chat_models import ChatOpenAI



llm = ChatOpenAI(

    base_url="http://localhost:8080/v1",

    api_key="not-needed",

    model="claude-opus-4-20250514"

)



response = llm.invoke("Explain quantum computing")

print(response.content)

```



### Using with Node.js



```javascript

const OpenAI = require('openai');



const client = new OpenAI({

  baseURL: 'http://localhost:8080/v1',

  apiKey: 'not-needed'

});



async function chat() {

  const response = await client.chat.completions.create({

    model: 'claude-opus-4-20250514',

    messages: [{ role: 'user', content: 'Hello!' }]

  });



  console.log(response.choices[0].message.content);

}

```



### Using with curl



```bash

# Basic request

curl -X POST http://localhost:8080/v1/chat/completions \

  -H "Content-Type: application/json" \

  -d '{

    "model": "claude-opus-4-20250514",

    "messages": [{"role": "user", "content": "Hello"}]

  }'



# With conversation ID

curl -X POST http://localhost:8080/v1/chat/completions \

  -H "Content-Type: application/json" \

  -d '{

    "model": "claude-opus-4-20250514",

    "conversation_id": "uuid-here",

    "messages": [{"role": "user", "content": "Continue our chat"}]

  }'



# With image

curl -X POST http://localhost:8080/v1/chat/completions \

  -H "Content-Type: application/json" \

  -d '{

    "model": "claude-opus-4-20250514",

    "messages": [{

      "role": "user",

      "content": [

        {"type": "text", "text": "What is this?"},

        {"type": "image_url", "image_url": {"url": "/path/to/image.png"}}

      ]

    }]

  }'

```



## 🔒 Security



- File access is controlled through configurable permissions

- MCP servers run in isolated processes

- No API key required (relies on Claude CLI authentication)

- Supports CORS for web applications

- Request ID tracking for audit trails



## ⚡ Performance Optimization



### Advanced Performance Features (via claude-code-sdk-rs)



The API leverages advanced performance optimizations from the underlying SDK:



#### Connection Pooling

- **First request**: 2-5 seconds (with pre-warmed connection pool)

- **Subsequent requests**: < 0.1 seconds (reusing existing connections)

- **Concurrent handling**: Multiple requests can share the connection pool



#### Client Modes

1. **OneShot Mode**: Simple, stateless queries (default)

2. **Interactive Mode**: Maintains conversation context across requests

3. **Batch Mode**: Process multiple queries concurrently for high throughput



#### Performance Metrics

```bash

# Example performance improvements with OptimizedClient:

- Sequential queries: ~5s for 5 queries

- Batch processing: ~1.5s for 5 queries (3x speedup)

- With connection pooling: < 100ms per query after warm-up

```



### Configuration for Performance



```toml

[claude]

max_concurrent_sessions = 10  # Increase for higher throughput

use_interactive_sessions = true  # Enable for conversation context

timeout_seconds = 300  # Adjust based on query complexity



[cache]

enabled = true

max_entries = 1000

ttl_seconds = 3600

```



### Best Practices



1. **Use the optimized REST endpoints** that leverage `OptimizedClient` from the SDK

2. **Enable connection pooling** for frequently used endpoints

3. **Use batch endpoints** for processing multiple queries

4. **Monitor performance** via the `/stats` endpoint

5. **Configure appropriate connection pool size** based on load



For detailed performance tuning, see the [SDK Performance Guide](https://github.com/ZhangHanDong/claude-code-api-rs/tree/main/claude-code-sdk-rs#performance-optimization).



## 🐛 Troubleshooting



### Common Issues



1. **"Permission denied" errors**

   ```bash

   # Enable file permissions

   export CLAUDE_CODE__FILE_ACCESS__SKIP_PERMISSIONS=true

   # Or use the startup script

   ./start_with_permissions.sh

   ```



2. **MCP servers not working**

   ```bash

   # Enable debug mode

   export CLAUDE_CODE__MCP__DEBUG=true

   # Check MCP server installation

   npx -y @modelcontextprotocol/server-filesystem --version

   ```



3. **High latency on first request**

   - This is normal as Claude CLI needs to start up

   - Subsequent requests will be faster due to process reuse



## 🤝 Contributing



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



1. Fork the repository

2. Create your feature branch (`git checkout -b feature/amazing-feature`)

3. Commit your changes (`git commit -m 'Add some amazing feature'`)

4. Push to the branch (`git push origin feature/amazing-feature`)

5. Open a Pull Request



## 📄 License



This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.



## 🙏 Acknowledgments



- Built on top of [claude-code-sdk-rs](https://github.com/ZhangHanDong/claude-code-api-rs/tree/main/claude-code-sdk-rs) - The robust Rust SDK for Claude Code CLI

- Powered by [Claude Code CLI](https://claude.ai/download) from Anthropic

- Inspired by OpenAI's API design for maximum compatibility

- Web framework: [Axum](https://github.com/tokio-rs/axum) for high-performance HTTP serving

- Async runtime: [Tokio](https://tokio.rs/) for blazing-fast async I/O



## 📞 Support



- [Report Issues](https://github.com/ZhangHanDong/claude-code-api-rs/issues)

- [Documentation](https://github.com/ZhangHanDong/claude-code-api-rs/wiki)

- [Discussions](https://github.com/ZhangHanDong/claude-code-api-rs/discussions)



---



Made with ❤️ by the Claude Code API team