# PRD: Claude Code Bridge Service - **Version:** 1.0 - **Date:** 2026-01-09 - **Status:** ✅ IMPLEMENTED --- ## Executive Summary CC-Bridge is a Go-based HTTP service that provides 100% Anthropic API-compatible interface while using the official Claude Code CLI (`claude -p`) under the hood. This preserves OAuth access legitimately without authentication hacks. **Problem Solved:** Anthropic shut down third-party OAuth access. Apps using OAuth tokens directly get: ``` LLM request rejected: This credential is only authorized for use with Claude Code and cannot be used for other API requests. ``` **Solution:** Wrap the official Claude CLI instead of fighting OAuth restrictions. --- ## Implementation Status ### Success Criteria - All Met ✅ - [x] Anthropic SDK works with zero code changes (just baseURL swap) - [x] OAuth preserved via legitimate Claude CLI usage - [x] Supports streaming (SSE) and non-streaming - [x] Tool use works (function calling via emulation) - [x] All Anthropic SDK examples work unchanged - [x] Performance acceptable (~100-200ms overhead) - [x] Vision support (images) - [x] Document support (PDF) - [x] Structured output (JSON schema) - [x] Extended thinking (simulated) ### Non-Goals (Deferred as Planned) - Multi-user auth/API keys (single-user bridge) - Rate limiting / quotas - Request logging / analytics - Multi-model support (OpenAI, Gemini) - WebSocket support --- ## Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ Client Application │ │ (Anthropic SDK, any language) │ │ │ │ const client = new Anthropic({ │ │ apiKey: "dummy", │ │ baseURL: "http://localhost:8321" │ │ }); │ └────────────────────────┬────────────────────────────────────┘ │ HTTP POST /v1/messages │ (Anthropic API format) ▼ ┌─────────────────────────────────────────────────────────────┐ │ CC-Bridge (Go HTTP Server) │ │ │ │ 1. Parse Anthropic request │ │ 2. Map to claude -p flags │ │ 3. Process vision/documents (extract to temp files) │ │ 4. Spawn CLI process │ │ 5. Parse CLI output │ │ 6. Return Anthropic response │ └────────────────────────┬────────────────────────────────────┘ │ spawn process │ claude -p --output-format json ▼ ┌─────────────────────────────────────────────────────────────┐ │ Claude Code CLI (official) │ │ │ │ Handles OAuth/API key authentication │ │ Uses user's Claude Pro/Max subscription │ │ 100% legitimate, no hacks │ └────────────────────────┬────────────────────────────────────┘ │ OAuth or API key ▼ Anthropic API (official) ``` --- ## API Compatibility ### Parity Summary | Category | Parity | Notes | |----------|--------|-------| | **SDK Compatibility** | 100% | All parameters accepted, code runs without changes | | **Content Types** | 100% | text, image, document, tool_use, tool_result | | **Tools & Structured Output** | 100% | Full tool use cycle, JSON schema | | **Streaming** | 100% | All 6 SSE event types | | **Sampling Parameters** | 0% | CLI limitation (see below) | ### Fully Supported Features | Feature | Status | Implementation | |---------|--------|----------------| | Non-streaming | ✅ | Direct CLI execution | | Streaming (SSE) | ✅ | All events: message_start, content_block_*, message_delta, message_stop | | System prompts | ✅ | Via `--append-system-prompt` | | Vision (images) | ✅ | Base64 and URL (JPEG, PNG, GIF, WebP) | | Documents (PDF) | ✅ | Base64 PDFs via Read tool | | Tool use | ✅ | Full cycle via prompt engineering emulation | | Tool choice | ✅ | `auto`, `any`, `tool` with JSON schema enforcement | | Structured output | ✅ | Native via `--json-schema` flag | | Extended thinking | ✅ Simulated | Via `<thinking>` blocks in prompt | | All models | ✅ | opus, sonnet, haiku | | `bash_20250124` | ✅ | Maps to CLI Bash tool | | `text_editor_20250124` | ✅ | Maps to CLI Edit tool | ### CLI Limitation: Sampling Parameters The Claude CLI **does not expose flags** for these parameters. CC-Bridge accepts them for SDK compatibility, but they have no effect: | Parameter | Status | Why | |-----------|--------|-----| | `temperature` | ⚠️ Accepted, ignored | No `--temperature` flag exists | | `top_p` | ⚠️ Accepted, ignored | No `--top-p` flag exists | | `top_k` | ⚠️ Accepted, ignored | No `--top-k` flag exists | | `max_tokens` | ⚠️ Accepted, ignored | No `--max-tokens` flag exists | | `stop_sequences` | ⚠️ Accepted, ignored | No `--stop-sequences` flag exists | **This is a CLI limitation, not a CC-Bridge limitation.** ### Not Available (Requires Direct API) | Feature | Status | Reason | |---------|--------|--------| | Computer use (mouse/keyboard) | ❌ | Requires `anthropic-beta` header | | Prompt caching | ❌ | Requires `anthropic-beta` header | | Batch API | ❌ | Different endpoint (`/v1/messages/batches`) | | Beta headers | ❌ | CLI blocks custom `anthropic-beta` headers | --- ## CLI Integration ### Model Name Mapping ``` Anthropic API → Claude CLI claude-opus-4-5-... → --model opus claude-sonnet-4-... → --model sonnet claude-haiku-3-5-... → --model haiku ``` ### Parameter Mapping (Implemented) | Anthropic API | Claude CLI Flag | Notes | |---------------|-----------------|-------| | `model` | `--model <name>` | Map to short names (opus/sonnet/haiku) | | `system` | `--append-system-prompt "<text>"` | Preserves CLI defaults | | `stream: false` | `--output-format json` | Non-streaming JSON | | `stream: true` | `--output-format stream-json --verbose` | SSE streaming | | `tools` | `--tools "Read,Bash,..."` | Map tool schemas → CLI tool names | | `output_format` | `--json-schema "<schema>"` | Structured output | | N/A | `--no-session-persistence` | Ephemeral sessions (always on) | | N/A | `--dangerously-skip-permissions` | Bridge handles security (always on) | ### Tool Name Mapping (Implemented) | API Tool Name | CLI Tool | |---------------|----------| | `bash`, `shell`, `execute` | Bash | | `read`, `read_file` | Read | | `write`, `write_file` | Write | | `edit`, `str_replace_based_edit_tool` | Edit | | `grep`, `search` | Grep | | `glob`, `find`, `list` | Glob | | `bash_20250124` (type) | Bash | | `text_editor_20250124` (type) | Edit | --- ## Project Structure (Final) ``` cc-bridge/ ├── src/ │ ├── main.go # HTTP server entry point │ ├── handler.go # Request handlers │ ├── types.go # Type definitions │ ├── cli.go # Claude CLI execution │ ├── mapper.go # API params ↔ CLI flags │ ├── streaming.go # SSE streaming support │ ├── tools.go # Tool use emulation │ ├── thinking.go # Extended thinking simulation │ ├── vision.go # Image/document processing │ └── *_test.go # Tests (171 total) ├── build/ # Compiled binaries (gitignored) ├── Makefile # Build commands ├── USERGUIDE.md # Complete user guide ├── CLAUDE.md # Development guide ├── PRD.md # This file └── README.md # Project overview ``` --- ## Configuration (Implemented) ### Command-Line Flags | Flag | Default | Description | |------|---------|-------------| | `--port` | `8321` | Server port | | `--host` | `0.0.0.0` | Bind address | ### Environment Variables | Variable | Default | Description | |----------|---------|-------------| | `CC_BRIDGE_PORT` | `8321` | Server port | | `CC_BRIDGE_HOST` | `0.0.0.0` | Bind address | | `CC_BRIDGE_DEBUG` | `false` | Enable debug logging | | `CLAUDE_CLI_PATH` | `claude` | Path to Claude CLI | | `CLAUDE_CLI_TIMEOUT` | none | CLI execution timeout (e.g., `30m`, `1h`) | --- ## Implementation Phases - All Complete ✅ ### Phase 1: MVP ✅ - [x] HTTP server with /v1/messages and /health endpoints - [x] Request parsing and validation - [x] CLI execution wrapper - [x] Response formatting - [x] Unit tests ### Phase 2: Streaming ✅ - [x] SSE response writer - [x] Stream parser (line-by-line JSON) - [x] Event transformation (CLI → Anthropic format) - [x] All 6 SSE event types ### Phase 3: Advanced Features ✅ - [x] Tool use emulation via prompt engineering - [x] Tool choice enforcement (auto/any/tool) - [x] JSON schema structured output - [x] Vision support (images) - [x] Document support (PDF) - [x] Extended thinking simulation ### Phase 4: Polish ✅ - [x] Graceful shutdown (SIGTERM) - [x] Request timeouts - [x] Debug logging - [x] CLI optimization flags - [x] Comprehensive test suite (171 tests) - [x] Documentation (README, USERGUIDE) --- ## Technical Decisions (Final) ### Language: Go - Fast process spawning - Low overhead - Single binary deployment - Excellent stdlib (http, json, exec) ### Dependencies: Minimal - `net/http` - HTTP server (stdlib) - `encoding/json` - JSON parsing (stdlib) - `os/exec` - Process spawning (stdlib) - No external dependencies ### CLI Flags Used ```bash claude -p \ --model sonnet \ --output-format json \ --no-session-persistence \ --dangerously-skip-permissions \ --append-system-prompt "..." \ --tools "Read,Bash,..." \ --json-schema "..." ``` --- ## Known Limitations 1. **Process overhead** - ~100-200ms latency per request from CLI spawning 2. **Single-user** - No multi-tenant support 3. **No session persistence** - Each request is independent (by design) 4. **Sampling parameters ignored** - Temperature, top_p, top_k use Claude defaults 5. **Tool use overhead** - ~150 extra tokens for tool emulation prompts --- ## Testing ### Test Coverage - 171 unit tests - All pass - Covers: request parsing, response formatting, tool mapping, streaming, vision, tools ### Run Tests ```bash make test # Unit tests make test-integration # Integration tests (requires Claude CLI) ``` --- ## Future Enhancements (Not Implemented) ### v1.1: Performance - Process pooling (reuse claude sessions) - Response caching - Connection pooling ### v1.2: Multi-User - API key authentication - Per-user rate limits - Usage tracking ### v1.3: Multi-Model - OpenAI API compatibility - Gemini API compatibility - Smart routing --- ## References ### Anthropic API Documentation - Messages API: https://docs.anthropic.com/en/api/messages - Streaming: https://docs.anthropic.com/en/api/messages-streaming - Tool Use: https://docs.anthropic.com/en/docs/build-with-claude/tool-use ### Claude CLI Documentation - Claude Code: https://code.claude.com - Agent SDK: https://platform.claude.com/docs/en/agent-sdk/overview --- **Implementation Complete!** 🎉