ranaroussi/cc-bridge

CC Bridge

Local Claude Code CLI bridge

An experiment that uses Claude Code CLI (`claude -p`) and returns the output in Antropic API compatible format

[!CAUTION]

Experimental - use at your own risk

CC Bridge is a personal exploration project. It is an unofficial wrapper around the Claude Code CLI intended for local experimentation, developer ergonomics, and integration testing.

• This project is not affiliated with, endorsed by, or sponsored by Anthropic.
• Anthropic’s terms, policies, and product behavior can change - you are responsible for ensuring your usage complies with the applicable terms and policies.
• If you need stable, supported programmatic access, use the official Anthropic API and credentials.

See USERGUIDE.md for complete setup and usage instructions.

---

Why this exists

I wanted a tiny sandbox to explore:

• Using claude -p in automated developer workflows (pipes, scripts, CI-style steps)
• Request/response shaping, streaming output, and robustness
• Logging, retries, timeouts, and failure modes
• How various developer tools behave when pointed at a local endpoint

This repo is best thought of as a fun experiment / prototype - not a recommended integration pattern, and not a production system.

---

The Drama That Started It All

One fateful day, developers everywhere woke up to find their OAuth tokens had been... grounded.

LLM request rejected: This credential is only authorized for use with
Claude Code and cannot be used for other API requests.

The internet panicked. Coffee was spilled. Slack channels burned. Someone probably flipped a table.

So I did what any reasonable developer would do: I asked Claude to hack itself.

And it worked. From the ashes of broken OAuth tokens rose CC-Bridge — a scrappy little Go server that said:

"Fine. You want me to use Claude Code? I'll use Claude Code. Maliciously compliantly."

CC-Bridge solves this by wrapping the official Claude CLI:

// Before (direct Anthropic API - OAuth broken):
const client = new Anthropic({
  apiKey: "sk-ant-oat01-...",  // OAuth token - REJECTED 💀
  baseURL: "https://api.anthropic.com"
});

// After (CC-Bridge - the smooth operator):
const client = new Anthropic({
  apiKey: "dummy",                     // Put whatever you want here, we don't care
  baseURL: "http://localhost:8321"     // Point to CC-Bridge
});

// Zero code changes needed! Your app doesn't even know the difference:
await client.messages.create({ model, messages, ... });  // Just works™

---

Features

What does this little bridge do? Everything.

• 100% Anthropic API compatible - Your existing code doesn't need to change a single character
• Streaming support - Full SSE streaming, tokens arriving faster than you can read them
• All models - Opus (for when you need big brain), Sonnet (the daily driver), Haiku (speed demon)
• Tool use - Full tool use cycle with emulation that actually works
• Vision & PDFs - Send images and documents, Claude sees all
• System prompts - Full support, whisper sweet instructions to your AI
• Graceful shutdown - Handles SIGTERM like a responsible adult

---

Prerequisites

Important: Claude Code CLI must be installed and authenticated before using CC-Bridge.

1. Install Claude Code CLI

npm install -g @anthropic-ai/claude-code
claude --version

2. Authenticate

claude
# Follow the prompts to sign in with your Anthropic account

3. Verify CLI Works

echo "Hello" | claude -p --model haiku --output-format json

---

Installation

Option 1: macOS Menu Bar App (Recommended for macOS)

Download the latest DMG from Releases:

1. Download CC-Bridge.dmg
2. Open the DMG and drag CC Bridge to Applications
3. Launch CC Bridge from Applications
4. The server starts automatically in the menu bar (port 8321)

The app is signed and notarized by Apple, so it runs without security warnings. Auto-updates are built-in via Sparkle.

Option 2: Pre-built Binaries

Download binaries for your platform from Releases:

# Example: macOS Apple Silicon
curl -L -o ccbridge https://github.com/ranaroussi/cc-bridge/releases/latest/download/ccbridge-darwin-arm64
chmod +x ccbridge
./ccbridge

Option 3: Build from Source

# Clone
git clone https://github.com/ranaroussi/cc-bridge.git
cd cc-bridge

# Build
make build

# Run (default port 8321)
./build/ccbridge

# Or with custom port
./build/ccbridge --port 9000

Test It

curl -X POST http://localhost:8321/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

---

Usage with SDKs

JavaScript/TypeScript

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: 'dummy',
  baseURL: 'http://localhost:8321',
});

const message = await client.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello!' }],
});

Python

import anthropic

client = anthropic.Anthropic(
    api_key="dummy",
    base_url="http://localhost:8321"
)

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}]
)

---

How It Works

The secret sauce? We're just a very polite middleman.

Your App (Anthropic SDK)
    │
    │  "Hey Anthropic, here's my request!"
    ↓
CC-Bridge (Go HTTP Server)
    │
    │  "Interesting... let me rephrase that for you"
    ↓  spawn("claude", ["-p", ...])
Claude CLI (Official, Blessed, Allowed™)
    │
    │  "One moment please..."
    ↓
Anthropic API
    │
    │  "Here's your response!"
    ↓
    🎉 Works perfectly

Key insight: We're not fighting OAuth — we're letting the official CLI do what it's allowed to do.

---

Configuration

Command-Line Flags

./build/ccbridge --port 9000 --host 127.0.0.1

Environment Variables

Environment variables are used as fallbacks when flags are not provided.

---

Project Structure

cc-bridge/
├── src/                   # Go HTTP server source
│   ├── 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
│   └── *_test.go          # Tests
├── app/macos/             # macOS menu bar app (Swift)
│   ├── Sources/           # Swift source files
│   ├── Package.swift      # Swift package manifest
│   └── create-app-bundle.sh  # App bundle creation script
├── build/                 # Compiled binaries (gitignored)
├── appcast.xml            # Sparkle auto-update feed
├── Makefile               # Build commands
├── USERGUIDE.md           # Complete user guide
├── CLAUDE.md              # Development guide
└── README.md              # This file

---

Running Tests

# Unit tests
make test

# Integration tests (requires authenticated Claude CLI)
make test-integration

---

API Compatibility

Parity Summary

100% Supported Features

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:

This is a CLI limitation, not a CC-Bridge limitation. Claude uses its default sampling behavior. For most use cases, this works fine. If you need precise control over sampling, you'll need direct API access.

Beta Features

Not Available (Requires Direct API)

---

CLI Optimizations

CC-Bridge uses these CLI flags for optimal performance:

---

Limitations

Nothing's perfect (except maybe Claude). Here's the fine print:

1. Process overhead - ~100-200ms latency per request from CLI spawning (a small price for freedom)
2. Single-user - No multi-tenant support (it's a bridge, not a highway)
3. No session persistence - Each request is independent (by design, we're stateless rebels)
4. Sampling parameters ignored - Temperature, top_p, top_k use Claude defaults (the CLI doesn't expose these knobs)

---

Structured Output

CC-Bridge supports structured output via the CLI's --json-schema flag:

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Extract the name and email"}],
    output_format={
        "type": "json_schema",
        "schema": {
            "type": "object",
            "properties": {
                "name": {"type": "string"},
                "email": {"type": "string"}
            },
            "required": ["name", "email"]
        }
    }
)

---

Extended Thinking (Simulated)

CC-Bridge simulates extended thinking via prompt engineering. When enabled, Claude shows its reasoning in <thinking> blocks:

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=2048,
    messages=[{"role": "user", "content": "What is 127 * 43?"}],
    thinking={"type": "enabled", "budget_tokens": 5000}
)

# Response includes thinking block:
# content[0].type == "thinking"
# content[0].thinking == "Let me work through this step by step..."
# content[1].type == "text"
# content[1].text == "127 × 43 = 5,461"

Note: This is simulated thinking via prompt engineering, not native API thinking tokens. The budget_tokens parameter is accepted for compatibility but doesn't limit actual token usage.

---

Tool Use (Emulated)

CC-Bridge emulates Anthropic's tool use protocol through prompt engineering. Your client code works exactly as it would with the real API:

# This works with CC-Bridge!
message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=[{
        "name": "get_weather",
        "description": "Get weather for a location",
        "input_schema": {
            "type": "object",
            "properties": {"location": {"type": "string"}},
            "required": ["location"]
        }
    }],
    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}]
)

# Claude returns tool_use, you execute, send tool_result back
# Exactly like the real API!

How it works: CC-Bridge injects tool schemas into the system prompt and instructs Claude to output tool calls in the native Anthropic JSON format. The response is parsed and returned as proper tool_use content blocks.

Trade-offs:

• ~150 extra tokens for tool instructions
• Each tool round-trip requires a CLI invocation
• Works reliably because Claude is trained on this format

---

Documentation

• User Guide - Complete setup and usage instructions
• Development Guide - For contributors

---

License

MIT License - see LICENSE for details.

---

Disclaimer

This project is not affiliated with, endorsed by, or sponsored by Anthropic. We're just some developers who needed their OAuth tokens to work again and found a creative solution.

Use at your own risk and ensure compliance with all applicable terms of service. We built this bridge, but you're the one crossing it.

---

Built with ☕ and mild frustration. May your tokens flow freely. ✨