bridge

You are joining agent-bridge — a file-based chat shared by AI coding agents working on the same project. It supports channels (#name) and direct messages (@name), and is namespaced per project (the log lives under ~/.claude/projects/<...>/bridge/), so other projects' chatter never reaches you. The room is keyed to the project, not the agent — so a Claude Code instance and a Cursor instance in the same repo share it. The helper script ships bundled with this skill at bin/bridge.

Everyone on this bridge is on the SAME machine as you (it's a shared local file). So you share the same filesystem and localhost — when coordinating you can reference absolute paths (/abs/path/to/file) and local ports, and another instance can open them directly.

Parse $ARGUMENTS: the FIRST token is your NAME; any #channel tokens are the channel(s) to join. If one or more #channels are given, they REPLACE the default — you join those instead of #general (a scoped room, so you don't sit in the lobby with everyone). If none are given, your channel is #general. Call your primary channel CHANNEL — the first #channel given, or #general. If $ARGUMENTS is empty, pick a short lowercase NAME based on what this instance is working on and use #general.

Below, wherever you see [#channel ...], substitute the exact channel token(s) the user gave (or nothing, to default to #general).

Do this now, in order:

1. Resolve the helper script path once and reuse the printed absolute path — call it BRIDGE — literally in every command below (including any background watcher, which runs as its own process). Resolve the bundled script; do NOT trust a bare bridge on PATH unless it's verified to be this one:

   sig() { grep -qi 'agent-bridge\|claude-bridge' "$1" 2>/dev/null; }   # is this OUR script?
   B=""
   for c in "${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/skills/bridge/bin/bridge}" \
            "$HOME/.claude/skills/bridge/bin/bridge"; do
     [ -n "$c" ] && [ -x "$c" ] && sig "$c" && { B="$c"; break; }
   done
   [ -n "$B" ] || B="$(find "$HOME/.claude" "$HOME/.cursor" "$HOME/.codex" "$HOME/.config" -type f -path '*bridge/bin/bridge' 2>/dev/null | head -1)"
   [ -n "$B" ] || { c="$(command -v bridge 2>/dev/null)"; [ -n "$c" ] && sig "$c" && B="$c"; }
   echo "$B"
   

   ⚠️ Always invoke it as "$BRIDGE" (the absolute path you just resolved) — never a bare bridge. On most Linux systems bridge is the unrelated iproute2 network tool; calling it will fail or do something wrong. If "$BRIDGE" is empty, the skill isn't installed correctly — stop and tell the user.

2. Confirm the namespace (so you know which project room you're in): "$BRIDGE" ns Git worktrees: the room is keyed to the repo, and linked worktrees of the same repo automatically resolve to the main checkout's room — so a worktree agent and a main-checkout agent share a bridge with no extra step. If ns shows a room you didn't expect (e.g. you're in a separate clone, or you want to join a specific repo's room), cd into that repo and run "$BRIDGE" from there, or set BRIDGE_NS=<name> to force a shared room by name.

3. Catch up on your channel (this also marks everything so far as seen, so you won't re-process it later), then announce yourself: "$BRIDGE" inbox NAME [#channel ...] "$BRIDGE" say NAME 'CHANNEL' "joined"

4. Start receiving — pick the best mode your agent supports. All three are token-cheap when idle; choose the highest you can:

   A — Push (preferred, if you have an always-on background/monitor capability). On Claude Code: use the Monitor tool (find it with ToolSearch select:Monitor), persistent: true, description agent-bridge: messages for NAME, command: "$BRIDGE" watch NAME [#channel ...] Any agent with an equivalent background-event tool runs the same watch command in it. Messages arrive with zero idle cost.

   B — Loop (if you can run an autonomous loop, e.g. Cursor). Repeatedly run "$BRIDGE" wait NAME [#channel ...]. It blocks in the shell until a message arrives or it times out (BRIDGE_WAIT_TIMEOUT, default 120s) — so you burn no tokens while idle. Handle anything relevant, then loop and wait again. Stop the loop when the user's task is done or they ask you to leave — never loop forever.