Claude Wrapper

OpenAI-compatible HTTP API wrapper for Claude Code CLI with Session Management

Transform your Claude Code CLI into a powerful HTTP API server with intelligent session management, streaming responses, and OpenAI-compatible tool calling.

🛠️ Tools-First Philosophy

Claude Wrapper provides OpenAI Tools API compatibility:

• Client-Side Execution: Tools run in your local environment
• OpenAI Standard: Uses standard tools array format from OpenAI specification
• MCP Compatible: Works with your local MCP tool installations

This approach gives you maximum flexibility with Claude's tool capabilities.

Key Features

• OpenAI Compatible: Drop-in replacement for OpenAI Chat Completions API
• Session Management: Automatic message history accumulation for conversation continuity
• Streaming Support: Real-time response streaming with Server-Sent Events

📦 Installation

# Install globally from npm
npm install -g claude-wrapper

After installation, you can use the CLI with either:

• wrapper (recommended short command)
• claude-wrapper (full package name)

🚀 Quick Start

wrapper

You'll see an interactive prompt asking if you want API key protection:

🚀 Starting Claude Wrapper...
🔐 API Key Protection Setup
Would you like to enable API key protection? (y/n):


- **Choose 'y'** to generate a secure API key for protection
- **Choose 'n' or press Enter** to run without authentication

Server starts at http://localhost:8000 - you're ready to make API calls!

📋 CLI Options

Usage: wrapper [options] [port]

Claude API wrapper with OpenAI compatibility

Arguments:
  port                 port to run server on (default: 8000) - alternative to
                       --port option

Options:
  -v, --version        output the version number
  -p, --port <port>    port to run server on (default: 8000)
  -d, --debug          enable debug mode (runs in foreground)
  -k, --api-key <key>  set API key for endpoint protection
  -n, --no-interactive disable interactive API key setup
  -P, --production     enable production server management features
  -H, --health-monitoring enable health monitoring system
  -s, --stop           stop background server
  -t, --status         check background server status
  -h, --help           display help for command

Authentication Options

Authentication is completely optional! You can also bypass the interactive setup:

# Skip interactive setup (no authentication)
wrapper --no-interactive
wrapper -n                         # shorthand

# Or provide API key directly
wrapper --api-key my-secure-key
wrapper -k my-secure-key           # shorthand

📡 API Endpoints

| Method | Endpoint | Description | | -------- | --------------------------- | --------------------------------------------- | | POST | /v1/chat/completions | Main chat completions with session support | | GET | /v1/models | List available Claude models (sonnet, opus) | | GET | /v1/sessions | List all active sessions | | GET | /v1/sessions/stats | Get session statistics | | GET | /v1/sessions/:id | Get specific session details | | DELETE | /v1/sessions/:id | Delete a specific session | | POST | /v1/sessions/:id/messages | Add messages to a session | | GET | /v1/auth/status | Check authentication configuration and status | | GET | /health | Service health check | | GET | /docs | Swagger UI | | GET | /swagger.json | OpenAPI 3.0 specification JSON schema |

🚀 CLI Usage

Starting the Server

# Start server on default port (8000)
wrapper

# Start server on specific port
wrapper 9999
wrapper --port 8080
wrapper -p 8080                    # shorthand

# Show version
wrapper --version
wrapper -v                         # shorthand

# Start with debug information (runs in foreground)
wrapper --debug
wrapper -d                         # shorthand

Managing the Background Service

# Check if server is running
wrapper --status
wrapper -t                         # shorthand

# Stop the background server
wrapper --stop
wrapper -s                         # shorthand

📚 Documentation

📖 Full Documentation - Comprehensive guide with detailed examples, production deployment, troubleshooting, and advanced configuration.

📄 License

MIT License - see LICENSE file for details.

⭐ Star this repository if you find it useful!
🐛 Report issues or suggest features at GitHub Issues

Get started today - npm install -g claude-wrapper and run wrapper to transform your Claude CLI into a powerful HTTP API!