Dai Ha
ef1e014b41
The orchestration contract had no distributable form. Every consuming project hand-copied a block of CLAUDE.md and hand-wrote an .mcp.json, and we keep a script whose only job is to notice those copies drifting apart. A plugin is versioned, installed once, and updates in place. Ships no credentials, deliberately: every secret is referenced by environment variable NAME and the value never enters a file, which is what makes the artifact safe to publish. The setup skill states the two rules that are easy to get wrong for the right-sounding reasons — the PR token must not be able to merge (a worker opens, the primary gates), and ANTHROPIC_BASE_URL must never be set by setup, because mounting the bridge must not move a session off subscription. The plugin root is plugin/, not the repo root. An installed plugin's .mcp.json is a committed file, while this repo's root .mcp.json is local-only and --skip-worktree; rooting the plugin at the repo would commit the primary's IDE servers and hand them to every worker — the exact failure CB-525 exists to prevent. Scope is client-side setup only. herdr and bridged stay separate services with their own lifecycles, and the skill refuses to install them rather than guess. It also refuses to accept /healthz as proof: health reports only that the daemon can reach herdr, and CB-521 showed it staying green while every spawn failed, so verification ends with a real spawn. Both manifests pass `claude plugin validate --strict`.
55 lines
1.9 KiB
Markdown
55 lines
1.9 KiB
Markdown
# claude-bridge (Claude Code plugin)
|
|
|
|
Makes a project **bridge-ready**: mounts the `bridged` MCP gateway and applies standard Claude Code
|
|
settings, so the session can orchestrate a fleet of delegated workers.
|
|
|
|
**This plugin ships no credentials.** Every secret is referenced by environment-variable *name*;
|
|
the values stay with the user. Nothing the plugin writes is unsafe to commit.
|
|
|
|
## What it is not
|
|
|
|
The plugin is the **client-side setup**, not the bridge. `bridged` is a separate daemon and `herdr`
|
|
is a separate PTY multiplexer, each with its own lifecycle and install. The plugin mounts an
|
|
already-running daemon and tells you what is missing when one isn't there — it deliberately does
|
|
not try to install system services on your behalf.
|
|
|
|
## Install
|
|
|
|
```shell
|
|
/plugin marketplace add ltms/claude-bridge
|
|
/plugin install claude-bridge@claude-bridge
|
|
```
|
|
|
|
Then, in the project you want to onboard:
|
|
|
|
```shell
|
|
/claude-bridge:setup
|
|
```
|
|
|
|
## What you get
|
|
|
|
| Component | Effect |
|
|
|---|---|
|
|
| `.mcp.json` | mounts `bridged` at `http://127.0.0.1:8765/mcp` for any session with the plugin enabled |
|
|
| `skills/setup` | `/claude-bridge:setup` — preflight, project settings, credential guidance, and verification |
|
|
|
|
Because the plugin carries its own `.mcp.json`, an installed plugin needs no project-level MCP
|
|
file at all. The setup skill writes one only when you want the mount to work *without* the plugin —
|
|
for teammates who haven't installed it, or for CI.
|
|
|
|
## Verifying a setup
|
|
|
|
The setup skill ends by requiring a **real spawn**, not a health check. `/healthz` only reports
|
|
that the daemon can reach herdr; a protocol mismatch between the daemon's adapter and the herdr
|
|
binary leaves health green while every spawn fails. Only a spawn that reaches `ready` proves the
|
|
fleet.
|
|
|
|
## Local development
|
|
|
|
```shell
|
|
claude --plugin-dir ./plugin
|
|
claude plugin validate ./plugin
|
|
```
|
|
|
|
`/reload-plugins` picks up edits without restarting the session.
|