{"id":"28a6740b-1e58-4058-86bd-1ec0f6e31520","slug":"msanchezdev-agent-bridge","kind":"skill","name":"agent-bridge","summary":"File-based group chat for Claude Code instances — group channels + DMs, namespaced per project. Installable as a skill or plugin.","owner":"msanchezdev","repoUrl":"https://github.com/msanchezdev/agent-bridge","license":"MIT","licenseTier":"permissive","trust":"community","stars":20,"match":null,"fewStars":false,"format":"skill","createdAt":null,"addedAt":"2026-10-14T06:07:24.768Z","logoUrl":"https://avatars.githubusercontent.com/u/35346082?u=7b31e0f1f5d7ef836c36b978670831430b489530&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","files-documents","communication"],"tags":["claude-code","claude-code-plugin","multi-agent","skills-sh"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-14T08:22:08.428Z","sample":false,"url":"https://conduits.dev/tools/msanchezdev-agent-bridge","language":"Shell","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# agent-bridge\n\nA file-based group chat for **AI coding agents** — group channels (`#name`) and\ndirect messages (`@name`), **namespaced per project** so chatter from other projects never\nreaches you. Multiple agent sessions on the same repo can coordinate, hand off work, and DM\neach other. The room is keyed to the **project, not the agent**, so a Claude Code instance and\na Cursor instance in the same repo share it.\n\nIt ships as a single **skill** (`bridge`, invoked with `/bridge`) plus a bundled helper\nscript, and is installable with the [`skills` CLI](https://github.com/vercel-labs/skills)\n(cross-agent) or as a Claude Code **plugin** (this repo doubles as a plugin marketplace).\n\n## Demo\n\nTwo real Claude Code instances on the same project — `backend` (left) and `frontend` (right) —\ncoordinating over the bridge. Each joins, catches up on history, and starts a background watcher;\nthen they exchange `#general` group posts and `@name` DMs, with every instance's watcher\nsurfacing the others' messages live.\n\n![Two Claude Code instances chatting over the bridge](assets/bridge-demo.gif)\n\n## Install\n\n### Option A — `skills` CLI (recommended, cross-agent)\n\n```bash\nnpx skills add msanchezdev/agent-bridge -a claude-code -g -y\n```\n\nThis copies the `bridge` skill (and its bundled `bin/bridge`) into `~/.claude/skills/`.\nDrop `-g` to install into the current project instead, and `-y` to skip prompts.\n\nWorks in other agents too — swap the `-a` target (`-a cursor`, `-a codex`, `-a opencode`, …).\nSee [Cross-agent support](#cross-agent-support) for what each one gets.\n\n### Option B — Claude Code plugin\n\nIn any Claude Code session:\n\n```\n/plugin marketplace add msanchezdev/agent-bridge\n/plugin install agent-bridge@agent-bridge\n```\n\nEither way, start it from any project with:\n\n```\n/bridge <your-name> [#group ...]\n```\n\n## Usage\n\n`/bridge alice` joins the current project's bridge as **alice** in the default `#general`\nchannel (plus your DMs).\n\n**Scoped channels:** pass a `#channel` to join *that* room instead of `#general`, so you\nonly see traffic relevant to your role: `/bridge designer #app`. Two instances in `#app`\ntalk to each other without anyone in `#general` (or other channels) hearing it. You still\nalways receive your own DMs (`@designer`). Pass several to join multiple\n(`/bridge designer #app #marketing`), or include `#general` explicitly to keep the lobby too.\n\nOnce joined, the agent surfaces only *relevant* incoming messages (DMs to you, or anything\nthat affects your work) — unrelated chatter is ignored silently.\n\n**Receive modes** — the agent picks the best its host supports, and **idle waiting never costs\nmodel tokens**:\n- **Push** — a background watcher (e.g. Claude Code's Monitor tool) streams messages the moment\n  they land. Zero idle cost.\n- **Loop** — agents that can run an autonomous loop (e.g. Cursor) call `bridge wait`, which\n  **blocks in the shell** until a message or a timeout. No tokens spent while idle.\n- **Poll** — any agent can call `bridge inbox` at natural checkpoints; it returns only what's new\n  since the last check (a per-user read cursor). Cheapest, but only sees messages while working.\n\nUnder the hood it calls the bundled helper:\n\n| Command | What it does |\n| --- | --- |\n| `bridge ns` | Print the active per-project namespace directory |\n| `bridge install [dir]` | Copy the helper onto `PATH` (default `~/.local/bin`) so any agent can call `bridge` |\n| `bridge say <me> <#channel\\|@to> msg…` | Post to a channel, or DM someone |\n| `bridge watch <me> [#channel …]` | **Push:** stream new messages (`tail -F`), for a Monitor-style tool |\n| `bridge wait <me> [#channel …]` | **Loop:** block until a new message (or `BRIDGE_WAIT_TIMEOUT`s, default 120) |\n| `bridge inbox <me> [#channel …]` | **Poll:** print only messages new since your last check |\n| `bridge history <me> [#channel …]` | Print all past messages for you (does not affect `inbox`) |\n| `bridge thread <me> <other>` | Show the full DM thread with someone |\n\nChannel defaulting is the same everywhere: your own DMs always, plus `#general` — or the given\n`#channel`(s) **instead** of `#general`.\n\n## How it works\n\n- One append-only `events.log` per namespace; every instance runs its own `watch`\n  (`tail -F` + filter), so messages are **broadcast** — reading never consumes them.\n- **Namespace** is per-project by default, living beside the project's memory at\n  `~/.claude/projects/<encoded-project-root>/bridge/`. Override with `BRIDGE_NS=<name>` to\n  use a shared/global room at `~/.claude/bridge/<name>/`.\n- Wire format is tab-separated: `<channel>\\t[<from>]\\t<message>`, where `channel` is\n  `#channel` or `@name`.\n- The namespace is derived from the project path, **independent of which agent is running** —\n  so different agents in the same repo automatically share a room.\n- **Git worktrees** of a repo all resolve to the **main** checkout's room (the namespace is\n  keyed off the shared git dir), so a worktree agent and a main-checkout agent share a bridge\n  with no extra step. A plain checkout is unaffected.\n- **Same machine:** because the room is a shared local file, every instance on a bridge is on\n  the same host — they share the filesystem and `localhost`, so they can hand each other\n  absolute paths and local ports.\n\n> **Heads-up for agents:** invoke the bundled helper by its **absolute path**, not a bare\n> `bridge` — on most Linux systems `bridge` is the unrelated `iproute2` network tool. The skill\n> resolves the bundled script and verifies it before use; `bridge install` puts a verified copy\n> on `PATH` if you want the short name.\n\n## Cross-agent support\n\nThe messaging engine (`bin/bridge`) is plain `bash`, and the room is keyed to the project, so\n**any agent that can run shell commands can post and read messages.** What differs is only *how*\neach agent gets notified:\n\n| Agent | Install | Receive mode |\n| --- | --- | --- |\n| Claude Code | `skills` CLI or plugin | **Push** (Monitor tool — instant) |\n| Cursor | `npx skills add … -a cursor` | **Loop** (`bridge wait` in an agent loop) |\n| Codex / OpenCode / Copilot | `npx skills add … -a <agent>` | **Loop** or **Poll** (`bridge wait` / `bridge inbox`) |\n\nThe skill auto-selects the best mode the host supports. Only Claude Code has true background\n**push**; everywhere else, the agent either loops on `bridge wait` (blocks in the shell — no\nidle token cost) or checks `bridge inbox` at natural points in its work. The honest tradeoff:\nnon-push agents notice messages when they next act, not while sitting idle.\n\n> Tip: run `bridge install` once to drop the helper on your `PATH`, so every agent just calls\n> `bridge` regardless of where the skill was installed.\n\n## Repo layout\n\n```\nagent-bridge/\n├── .claude-plugin/\n│   ├── plugin.json          # plugin manifest (root of repo == the plugin)\n│   └── marketplace.json     # marketplace catalog pointing at \"./\"\n├── skills/\n│   └── bridge/\n│       ├── SKILL.md         # the /bridge skill\n│       └── bin/bridge       # bundled helper script (travels with the skill)\n├── README.md\n└── LICENSE\n```\n\nThe helper lives **inside** the skill directory so it survives a skill-only copy (the `skills`\nCLI) as well as a full plugin install. `SKILL.md` resolves the script's absolute path at\nruntime, so it works regardless of where it landed on disk.\n\n## Local development\n\nPoint Claude Code at the local plugin directory without publishing:\n\n```\nclaude --plugin-dir .\n```\n\n## License\n\nMIT\n"}