Claude Bridge

A tiny local HTTP proxy in front of the Claude CLI. Any app on your machine can POST a prompt to http://localhost:8787 and get an answer back — billed against the Claude Pro/Max subscription the CLI is logged into, not against a pay-per-token API key.

Use this when

• You already pay for Claude Pro/Max and don't want a second API bill.
• You want a Chrome extension, shell script, or side project to talk to Claude without managing keys.
• You're prototyping in tools that can't speak the Anthropic SDK directly.

Don't use this when

• You need the lowest possible latency. The direct API is 2–3× faster.
• You're shipping a product to other people. They don't have your CLI session.
• You're processing thousands of requests per day. You'll hit subscription throttles.

Requirements

• Node.js 18+
• The Claude Code CLI, installed and logged in:

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

Installation

npm install -g @olakunlevpn/claude-bridge

The package is scoped but the CLI is still invoked as claude-bridge.

Usage

Start the server:

claude-bridge

Send a prompt:

curl -s http://localhost:8787 \
  -H "Content-Type: application/json" \
  -d '{"userText":"What is 2+2?"}' | jq -r .answer

Check the health endpoint:

curl http://localhost:8787/health
# {"status":"ok","model":"default"}

API

POST /

POST / HTTP/1.1
Host: localhost:8787
Content-Type: application/json

{
  "systemPrompt": "You are a concise answer bot.",
  "userText": "Which is the capital of France? A) Berlin B) Paris C) Rome",
  "model": "haiku"
}

| Field | Required | Notes | | -------------- | -------- | ------------------------------------------------------------- | | userText | yes | The user prompt. | | systemPrompt | no | When provided, prepended to userText with a --- separator.| | model | no | Per-request model override. Falls back to BRIDGE_MODEL. |

Response:

{ "answer": "B" }

Error responses ({ "error": "..." }):

| Status | Meaning | | ------ | ----------------------------------------------------------------- | | 400 | userText missing or not a string, or model not a string. | | 401 | BRIDGE_TOKEN is set and the request didn't pass auth. | | 405 | Non-POST on /. | | 413 | Request body exceeds the 1 MB limit. | | 500 | Claude CLI failed or the request timed out. |

GET /health

{ "status": "ok", "model": "default" }

Configuration

Configure via environment variables, or drop a .env file in either location:

• ./.env — per-project, takes priority
• ~/.claude-bridge/.env — global default

Shell environment variables always win over both files.

| Variable | Default | Purpose | | -------------------- | -------------- | ------------------------------------------------------------- | | BRIDGE_PORT | 8787 | Port to listen on | | BRIDGE_TIMEOUT_MS | 30000 | Per-request timeout in milliseconds | | BRIDGE_MODEL | (CLI default)| Default model. A per-request model in the body overrides it.| | BRIDGE_TOKEN | (unset) | Enables Authorization: Bearer ... when set | | CLAUDE_CMD | claude | Path or name of the Claude CLI binary |

Example .env:

BRIDGE_PORT=9000
BRIDGE_MODEL=haiku
BRIDGE_TIMEOUT_MS=60000

Or inline:

BRIDGE_PORT=9000 BRIDGE_MODEL=haiku claude-bridge

Using from a Chrome extension

Add to manifest.json:

"host_permissions": ["http://localhost/*", "http://127.0.0.1/*"]

Call it:

const response = await fetch("http://localhost:8787", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ systemPrompt, userText })
});
const { answer } = await response.json();

Security

• The server binds to 127.0.0.1 only, so it's not reachable from the network.
• Requests larger than 1 MB return 413 Payload Too Large.
• Authentication is optional. Set BRIDGE_TOKEN to require Authorization: Bearer <token> on all requests except OPTIONS and GET /health:

BRIDGE_TOKEN=$(openssl rand -hex 24) claude-bridge

curl -s http://localhost:8787 \
  -H "Authorization: Bearer $BRIDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userText":"What is 2+2?"}'

Without BRIDGE_TOKEN, anyone who can reach localhost on your machine can call the bridge. Don't run it unauthenticated on a shared box.

Licensing and terms

Claude Bridge calls the official Claude CLI via spawn. Make sure your usage stays within Anthropic's Acceptable Use Policy and the terms of your subscription. Extracting OAuth tokens outside the CLI is a separate thing that Anthropic has banned — this project does not do that; it just runs the CLI.

Contributing

Issues and pull requests welcome at github.com/Olakunlevpn/claude-bridge. For major changes, open an issue first.

Credits

• Olakunlevpn

License

The MIT License (MIT). See LICENSE.