Claude Bridge

Claude Bridge

A local-first, cross-machine message bus for independent coding agents.

Claude Bridge lets coding-agent sessions on different machines exchange ordered messages through named channels. The relay is self-hosted, uses SQLite by default, and exposes MCP, a small JSON API, a dashboard, and a terminal UI.

It does not call a model API and does not require agents to share a filesystem or process. Claude Code motivated the project, but the core is MCP-based and is not coupled to Anthropic.

Forward-build notice: this source tree identifies as 1.2.0.dev1. It is

a development build beyond the latest stable PyPI release. Review the

changelog

and 0.9-to-1.2 migration guide

before replacing a stable deployment.

Why use it?

• Keep agents on Windows, macOS, Linux, or a remote host in their own sessions.
• Send work, results, review requests, and artifact references without remote shell access.
• Use durable history and consumer cursors to recover after a client restart.
• Retry sends safely with an idempotency key.
• Observe the same relay through MCP, a browser dashboard, the TUI, or REST.
• Run locally or across a private LAN/tailnet with an explicit security policy.

Claude Bridge is a transport, not an autonomous orchestrator. Receiving a message never authorizes an agent to execute it.

Transports

The automated suite performs a real MCP SDK handshake against /mcp. Vendor clients are not launched in CI. See the evidence-based compatibility matrix.

Architecture

flowchart TB

A["Claude Code / Codex / MCP client"] -->|"Streamable HTTP /mcp"| B["Claude Bridge"] C["Local MCP client"] -->|"stdio"| B D["Dashboard / TUI / script"] -->|"REST + event SSE"| B B --> E[("SQLite")]

Messages and live-notification records are committed to SQLite in one transaction. HTTP processes poll that durable outbox (500 ms by default), so a write from a separate stdio process is propagated to connected dashboard/TUI event streams. Durable channel history remains authoritative across restarts.

Install

python -m pip install claude-code-bridge

Install the terminal UI as well:

python -m pip install "claude-code-bridge[tui]"

The PyPI distribution is named claude-code-bridge because claude-bridge was already assigned to an unrelated project. The command and Python package remain claude-bridge and claude_bridge.

From a source checkout:

git clone https://github.com/constripacity/Claude-Bridge.git

cd Claude-Bridge python -m pip install -e ".[dev]"

Start safely

Local-only HTTP mode is the default:

claude-bridge

This listens on 127.0.0.1:8765. Open http://127.0.0.1:8765/ for the dashboard or connect an MCP client to http://127.0.0.1:8765/mcp.

Local stdio mode does not open a network listener:

claude-bridge --stdio

Cross-machine server

Network binding is deliberately fail-closed. Supply the address clients put in their URL as a trusted host and require a token:

export CLAUDE_BRIDGE_AUTH_TOKEN="$(openssl rand -hex 32)"

claude-bridge \ --host 0.0.0.0 \ --trusted-host 100.64.0.10

Here 100.64.0.10 might be the server's tailnet address. A DNS deployment would use a value such as bridge.example.internal. --trusted-host values are hostnames or IP addresses, without a URL scheme or path, and the option is repeatable.

Two independent checks are required:

1. --trusted-host controls which HTTP Host names are accepted; and
2. the Bearer token controls who can use protected endpoints.

For a deliberately unauthenticated private test network, replace the token with --allow-unauthenticated-network. That is an explicit risk acceptance, not the recommended production setup.

Use --tls-cert and --tls-key, an HTTPS reverse proxy, or an encrypted overlay network before sending sensitive content across an untrusted network. See the security policy for the complete trust model.

Container

The official image also fails closed. A network deployment must provide its trusted host and authentication policy:

export CLAUDE_BRIDGE_AUTH_TOKEN="$(openssl rand -hex 32)"

docker run --rm -p 8765:8765 \ -v claude-bridge-data:/data \ -e CLAUDE_BRIDGE_AUTH_TOKEN \ -e CLAUDE_BRIDGE_TRUSTED_HOSTS="100.64.0.10" \ ghcr.io/constripacity/claude-bridge:latest

The SQLite database is stored in /data. Release images use exact and major/minor tags; edge tracks main.

Connect a client

Claude Code

Remote Streamable HTTP:

claude mcp add --transport http -s user claude-bridge \

http://127.0.0.1:8765/mcp

Local stdio:

claude mcp add -s user claude-bridge -- claude-bridge --stdio

For a protected remote endpoint, attach the matching Authorization header using the option supported by the installed Claude Code version. Legacy configurations can continue to target /sse with --transport sse while they migrate.

Codex

Local stdio in ~/.codex/config.toml:

[mcp_servers.claude_bridge]

command = "claude-bridge" args = ["--stdio"]

Remote Streamable HTTP:

[mcp_servers.claude_bridge]

url = "http://127.0.0.1:8765/mcp" bearer_token_env_var = "CLAUDE_BRIDGE_AUTH_TOKEN"

These examples follow the transports each client documents. The repository's CI verifies MCP protocol behavior, not a full vendor-client launch. See compatibility matrix before making support claims.

MCP tools

Tool results include structured data for clients that support MCP structured content and a readable text representation for compatibility.

Reliable task/result example

The orchestrator sends a structured task with a stable retry key:

bridge_send(

channel="payments:worker", sender="windows-orchestrator", idempotency_key="job-802-task", message={ "schema_version": 1, "type": "task", "content": {"action": "run_tests", "target": "payments"}, "thread_id": "payments-42", "correlation_id": "job-802" } )

The worker waits using its persisted consumer identity:

bridge_wait(

channel="payments:worker", consumer_id="mac-worker", timeout_seconds=20 )

After applying the task successfully, it advances its cursor:

bridge_ack(

channel="payments:worker", consumer_id="mac-worker", message_id=" " )

It can then send a result to a return channel using the same thread_id and correlation_id. Acknowledgement supplies at-least-once processing semantics; it does not make arbitrary external side effects exactly once.

The complete envelope, retry, cursor, and retention contract is documented in protocol reference.

Task queue (work distribution)

Messages fan out — every consumer cursor sees every message. A task queue is the opposite: each task is claimed by exactly one worker. Point a fleet of worker agents at a channel and they share the work without ever double-processing it.

The orchestrator enqueues tasks (dedup-safe with an idempotency key):

bridge_enqueue(

channel="builds", payload={"repo": "payments", "action": "run_tests"}, max_attempts=3, idempotency_key="build-802" )

Each worker claims the next task, holding a lease (a visibility timeout). Two workers never get the same task; wait_seconds long-polls an empty queue:

bridge_claim(channel="builds", consumer="worker-3", lease_seconds=300, wait_seconds=20)

-> { task_id, payload, attempts, lease_token, lease_expires_at }

It finishes before the lease expires — complete on success, fail to retry — both fenced by the lease_token, so a reclaimed task can't be clobbered:

bridge_complete(channel="builds", task_id="tsk_…", lease_token="…", result={"passed": 105})

bridge_fail(channel="builds", task_id="tsk_…", lease_token="…", requeue=true, retry_delay_seconds=30)

If a worker crashes and never resolves its task, the lease expires and the task is requeued automatically — or dead-lettered once max_attempts is exhausted. This is at-least-once delivery, so make task handlers idempotent. bridge_tasks(channel="builds") shows the queue's per-status counts.

Channels

Channels are created on first write. A readable convention is : :

payments:orchestrator

payments:worker payments:events payments:review general:status

A channel name is routing, not authorization. In the current shared-token model, any authorized client can read, write, or clear any channel.

Dashboard, TUI, and JSON API

The dashboard is served at / unless --no-dashboard is used. It consumes the JSON API and the per-channel event stream. Its React application, fonts, and other runtime assets are bundled with the package, so loading the dashboard does not contact a third-party CDN. A restrictive Content Security Policy is applied to the static application.

Run the TUI:

python -m claude_bridge.tui

python -m claude_bridge.tui \ --url http://100.64.0.10:8765 \ --sender mac

The TUI reads CLAUDE_BRIDGE_AUTH_TOKEN from the environment, keeping the secret out of the process command line.

Core HTTP endpoints:

| POST /api/send | Send legacy text or a pro