claude-max-bridge

A small FastAPI server that exposes an OpenAI-compatible /v1/chat/completions endpoint and translates each request into a claude CLI subprocess call. This lets LiteLLM (or any OpenAI-compatible client) consume a Claude Max subscription through the locally-installed claude binary without needing an Anthropic API key.

How it works

1. Client sends an OpenAI chat-completions request (streaming or non-streaming).
2. The bridge extracts the system prompt and conversation turns.
3. It spawns claude --print --output-format stream-json --input-format stream-json ... and pipes the conversation as NDJSON to stdin.
4. It parses the NDJSON stdout, computes text deltas from partial assistant messages, and re-emits them as OpenAI SSE chunks (or buffers for non-streaming).
5. Usage totals from the result event are forwarded in the final response.

Authentication is handled entirely by the claude binary; the bridge just bind-mounts the existing ~/.claude credentials directory.

Environment variables

Variable	Default	Description
CLAUDE_BIN	/usr/local/bin/claude	Path to the claude CLI binary
CLAUDE_HOME	/root/.claude	Path to the Claude config / credentials directory
LOG_LEVEL	INFO	Python logging level
REQUEST_TIMEOUT_S	120	Per-request subprocess timeout in seconds

Running with Docker

docker build -t claude-max-bridge .

docker run -d \
  --name claude-max-bridge \
  -p 8000:8000 \
  -v /usr/local/bin/claude:/usr/local/bin/claude:ro \
  -v /root/.claude:/root/.claude:ro \
  claude-max-bridge

Supported models

• claude-sonnet-4-6 (default fallback)
• claude-opus-4-5
• claude-haiku-4-5
• claude-opus-4-0
• claude-sonnet-3-7
• claude-haiku-3-5

Unknown model names in requests fall back to claude-sonnet-4-6.

LiteLLM configuration

Add these entries to your litellm_config.yaml:

model_list:
  - model_name: claude-sonnet-4-6
    litellm_params:
      model: openai/claude-sonnet-4-6
      api_base: http://claude-max-bridge:8000/v1
      api_key: "unused"           # required by LiteLLM but ignored by bridge

  - model_name: claude-opus-4-5
    litellm_params:
      model: openai/claude-opus-4-5
      api_base: http://claude-max-bridge:8000/v1
      api_key: "unused"

Replace claude-max-bridge with the actual hostname or IP where the bridge container is running.

Endpoints

Method	Path	Description
GET	/health	Liveness check, always returns 200 OK
GET	/v1/models	Lists supported models
POST	/v1/chat/completions	OpenAI-compatible chat completions

Notes

• temperature, top_p, and other sampling parameters are silently ignored (logged at DEBUG level) because the CLI does not expose them.
• Rate-limit responses from the CLI are translated to HTTP 429.
• Auth errors from the CLI are translated to HTTP 401.
• The subprocess is killed on client disconnect or timeout.