Claude-Bridge

# Claude Bridge

<!-- mcp-name: io.github.constripacity/claude-code-bridge -->

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

[![CI](https://github.com/constripacity/Claude-Bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/constripacity/Claude-Bridge/actions/workflows/ci.yml)
![Python](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![MCP](https://img.shields.io/badge/MCP-Streamable_HTTP-orange)

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](https://github.com/constripacity/Claude-Bridge/blob/main/CHANGELOG.md)
> and [0.9-to-1.2 migration guide](https://github.com/constripacity/Claude-Bridge/blob/main/docs/MIGRATING-0.9-TO-1.2.md)
> 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

| Interface | Path or command | Purpose |
|---|---|---|
| MCP Streamable HTTP | `/mcp` | Recommended remote MCP transport |
| MCP stdio | `claude-bridge --stdio` | Local subprocess transport |
| Legacy MCP HTTP+SSE | `/sse` and `/messages/` | Existing configurations during migration |
| Channel event SSE | `/events/channel/<channel>` | Dashboard, TUI, and custom listeners; not MCP |
| JSON API | `/api/*` | Browser, scripts, and integrations |

The automated suite performs a real MCP SDK handshake against `/mcp`. Vendor
clients are not launched in CI. See the evidence-based
[compatibility matrix](https://github.com/constripacity/Claude-Bridge/blob/main/docs/COMPATIBILITY.md).

## Architecture

```mermaid
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

```bash
python -m pip install claude-code-bridge
```

Install the terminal UI as well:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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](https://github.com/constripacity/Claude-Bridge/blob/main/SECURITY.md)
for the complete trust model.

### Container

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

```bash
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:

```bash
claude mcp add --transport http -s user claude-bridge \
  http://127.0.0.1:8765/mcp
```

Local stdio:

```bash
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`:

```toml
[mcp_servers.claude_bridge]
command = "claude-bridge"
args = ["--stdio"]
```

Remote Streamable HTTP:

```toml
[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](https://github.com/constripacity/Claude-Bridge/blob/main/docs/COMPATIBILITY.md)
before making support claims.

## MCP tools

| Tool | Purpose |
|---|---|
| `bridge_send` | Send legacy text or a protocol-v1 message; supports idempotent retries |
| `bridge_receive` | Read a bounded page using a message cursor or durable consumer cursor |
| `bridge_wait` | Wait up to 55 seconds for new messages without rapid polling |
| `bridge_ack` | Monotonically advance a consumer's channel-scoped cursor |
| `bridge_channels` | List active channels and counts |
| `bridge_ping` | Check bridge health and capabilities |
| `bridge_status` | Summarize recent activity across channels |
| `bridge_clear` | Delete every message (and task) in one channel |
| `bridge_enqueue` | Add a task to a channel's work queue (exclusive; claimed once) |
| `bridge_claim` | Atomically claim the next task with a lease; long-poll with `wait_seconds` |
| `bridge_complete` | Mark a claimed task done, fenced by its `lease_token` |
| `bridge_fail` | Fail a claimed task — requeue with backoff, or dead-letter |
| `bridge_tasks` | Inspect a channel's queue: per-status counts and a task list |

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:

```text
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:

```text
bridge_wait(
  channel="payments:worker",
  consumer_id="mac-worker",
  timeout_seconds=20
)
```

After applying the task successfully, it advances its cursor:

```text
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](https://github.com/constripacity/Claude-Bridge/blob/main/docs/PROTOCOL.md).

### 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):

```text
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:

```text
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