Claude Bridge

<!-- mcp-name: io.github.constripacity/claude-code-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="<processed-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 <project>:<purpose>:

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:

The event stream can drop a slow subscriber after its buffer fills; durable history remains authoritative. Reconnect with the last message ID and honor cursor_stale or replay_truncated by fetching history explicitly.

Authentication and browser boundaries

Set CLAUDE_BRIDGE_AUTH_TOKEN, --auth-token-file, or --auth-token. The literal CLI form can appear in process listings; the environment variable or a permission-restricted file is preferred.

When enabled, protected REST, MCP, and event endpoints require:

Authorization: Bearer <token>

/status remains public and deliberately contains minimal information. The static dashboard shell may be reachable, but protected data APIs still require the token.

Unsafe browser mutations are restricted by Origin, JSON endpoints require a JSON media type, and Host headers are allowlisted. Extra browser origins are configured independently with repeatable --cors-origin flags.

The dashboard submits the Bearer token once to POST /api/session and receives a short-lived opaque HttpOnly, SameSite=Strict cookie. The master token is not written to local storage or a URL. Event streams authenticate with that cookie; ?token= query authentication is rejected. Logging out revokes the session, and a server restart invalidates all in-memory dashboard sessions.

Configuration

CLI values take precedence where a matching flag exists. Invalid numeric or boolean environment values fail during startup with a configuration error.

Persistence and operational limits

• SQLite runs in WAL mode and is suitable for a personal or small-team relay.
• The server is not currently a multi-node or high-availability message broker.
• One HTTP worker plus cooperating stdio processes can share the WAL database;

the durable outbox propagates their live events. This remains a small-scale SQLite design, not a multi-node or enterprise broker.

• Retention can invalidate old cursors. Important work products belong in a

repository or artifact store, not only in bridge history.

• The shared Bearer token does not provide identity or per-channel permissions.
• No benchmark claim is made without a reproducible benchmark and environment.

The future operations and authorization milestones are in roadmap.

Development

python -m pip install -e ".[dev]"
ruff check claude_bridge tests
pytest -v
python -m build

CI tests Linux across Python 3.10–3.13 and runs current-version smoke jobs on Windows and macOS. The real-socket MCP test covers initialization, tool listing, send, receive, wait, and acknowledgement through the official SDK. A separate job builds the sdist and wheel, validates their metadata, installs each artifact into a clean environment, and checks the CLI.

Read the contribution guide before proposing a new capability. For a vulnerability, use the private process in the security policy, not a public issue.

Roadmap

The current sequence is:

1. 1.2 — secure Streamable HTTP, structured messages, idempotency, and durable

consumers;

1. 1.3 — native client diagnostics and an experimental Claude Channels

companion;

1. 1.4 — individual identities, scopes, ACLs, quotas, and token rotation;
2. 1.5 — observability, operational tooling, and an optional scalable

backend; and

1. 2.0 — federation and an optional A2A adapter if real usage demands them.

Each milestone and its non-goals are defined in the roadmap.

License

MIT — see the license.

Founded and maintained by Constripacity.