Dai Ha
91 lines
4.7 KiB
Markdown
91 lines
4.7 KiB
Markdown
# claude-bridge
|
|
|
|
A **subscription-safe bridge** that lets a primary **Claude Code (Opus 4.8, on Pro/Max)**
|
|
session drive a **secondary Claude agent running a different model** via its own
|
|
`ANTHROPIC_BASE_URL` — without ever putting a proxy on the primary session.
|
|
|
|
Sibling of [`crush-bridge`](https://git.ltms.dev/systems/vms) (which drives a headless
|
|
**Crush** worker on GX10 DeepSeek). `claude-bridge` keeps the worker a *real Claude Code
|
|
process*, so it inherits `CLAUDE.md`, hooks, skills, and MCP — just pointed at a
|
|
cheaper/local model.
|
|
|
|
## Leading approach — herdr-centric message server (`bridged`)
|
|
|
|
A small always-on message server, **`bridged`**, controls
|
|
[herdr](https://herdr.dev) (an agent multiplexer) over its Unix-socket API and exposes a
|
|
clean 2-way messaging API as an **MCP server that both the primary and the workers mount** —
|
|
one unified Claude setup and the **sole communication gateway** (REST/SSE stays for non-Claude
|
|
clients; any broker is `bridged`-internal, below the gateway).
|
|
herdr owns the PTYs, multiplexing, persistence, and **agent-status events**; `bridged` owns
|
|
policy (subscription boundary, session lifecycle, status-gated delivery) and the client
|
|
contract. The worker `claude` launches with `ANTHROPIC_BASE_URL=https://ollama.ltms.dev` + a
|
|
bearer token; the primary Opus stays env-clean and calls `bridged`'s MCP tools.
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
OPUS["Opus — primary<br/>(Claude Code, env CLEAN)<br/>MCP client"]
|
|
subgraph BD["bridged — standalone daemon (not a claude process)"]
|
|
SRV["SERVER face<br/>MCP · REST/SSE · policy"]
|
|
CLI["CLIENT face<br/>herdr socket"]
|
|
SRV --> CLI
|
|
end
|
|
HERDR["herdr<br/>panes · agent-status"]
|
|
W["worker claude pane<br/>ANTHROPIC_BASE_URL set<br/>MCP client"]
|
|
M["ollama.ltms.dev<br/>(worker model)"]
|
|
|
|
OPUS -->|"MCP bridge_send (blocks)"| SRV
|
|
W -.->|"MCP bridge_reply"| SRV
|
|
CLI -->|"Unix socket<br/>send_text · events.subscribe"| HERDR
|
|
HERDR -->|"drives PTY"| W
|
|
W -->|"inference"| M
|
|
|
|
classDef ext fill:#2b6cb0,stroke:#1a365d,color:#ffffff;
|
|
classDef core fill:#2f855a,stroke:#22543d,color:#ffffff;
|
|
class OPUS ext
|
|
class SRV,CLI,HERDR core
|
|
```
|
|
|
|
- **Subscription boundary:** the *primary* never sets `ANTHROPIC_BASE_URL` (stays on
|
|
Pro/Max). Only the *secondary* process is off-subscription — and `bridged` itself is a
|
|
plain daemon (no Anthropic quota), so it may poll/subscribe freely.
|
|
- **One gateway (unified MCP setup):** `bridged` is the **sole communication path** for every
|
|
Claude session. Primary and workers each mount it as an MCP server (one `claude mcp add`
|
|
line, same on both) and talk over MCP tools — `bridge_send` / `bridge_reply` / `bridge_ask` /
|
|
`bridge_status`. **No Claude session ever addresses a broker, a peer, or the network
|
|
directly**; any queue is `bridged`-internal. MCP tool I/O never sets `ANTHROPIC_BASE_URL`, so
|
|
mounting the bridge is subscription-safe by construction.
|
|
- **How the primary consumes a reply:** a single **blocking MCP call** (`bridge_send`);
|
|
`bridged` holds it open until the worker calls `bridge_reply` or its turn hits
|
|
`agent_status=done`, then returns the reply as the tool result. No cross-turn busy-poll, so
|
|
no quota burn. SSE is an optional side-channel for humans/dashboards watching status.
|
|
- **Worker → primary** rides `bridged`'s **MCP rendezvous** — the reply resolves the primary's
|
|
blocking call (or, for detached work, `bridged` **injects the primary's idle pane** when it's
|
|
ready), so *no keystroke-into-primary and no broker are involved, even single-host*. The one
|
|
exception: a split-host primary that isn't a herdr pane wakes via its own `Stop`-hook, which
|
|
polls **`bridged`** (never a broker). See the wiki for the two topologies.
|
|
- **Different model per process** sidesteps Claude Code's lack of per-subagent provider
|
|
routing — the worker isn't a subagent, it's its own configured process.
|
|
- **AgentAPI** ([`coder/agentapi`](https://github.com/coder/agentapi)) is retained only as a
|
|
swappable *fallback injector* behind the same interface. See the wiki for the full
|
|
design, comparison, and rationale.
|
|
|
|
## Docs
|
|
|
|
Full design, setup, and operations live in the **[wiki](https://git.ltms.dev/lms/claude-bridge/wiki)**,
|
|
vendored here as a submodule under [`wiki/`](./wiki):
|
|
|
|
```bash
|
|
git clone --recurse-submodules ssh://git@git.ltms.dev:2224/lms/claude-bridge.git
|
|
# or, after a plain clone:
|
|
git submodule update --init
|
|
```
|
|
|
|
Edit docs in `wiki/`, then `cd wiki && git commit && git push` to publish them to the
|
|
Gitea wiki.
|
|
|
|
## Status
|
|
|
|
🟢 Design — herdr-centric **`bridged`** message server selected as the primary approach
|
|
(2026-07-11), superseding the AgentAPI plan (2026-07-08). AgentAPI retained as fallback
|
|
injector.
|