agent-bridge

How to invoke (host-specific)

The bridge exposes the same capabilities everywhere; only the call syntax differs:

• Claude Code / Codex / MCP hosts — call the tools directly: whoami, send, read, list_agents, join_room, who_is_in, use_bridge, set_name, spawn_agent.
• Pi — call the single tool agent_bridge with an action: agent_bridge action=send to=... message=..., agent_bridge action=whoami, etc. (actions: send, read, whoami, list_agents, join_room, use_bridge, set_name, spawn_agent).

Below, an action like whoami means "the whoami tool" on Claude/Codex, and "agent_bridge action=whoami" on Pi.

When to Use

• The user says "activa bridge harness", "agent bridge", or "activa bridge".
• The user asks who is connected / quién está conectado on the bridge.
• You need to send to, or coordinate with, another agent over NATS.

Routing model (read this first)

Activation Sequence (run in order, every time)

1. Identify yourself — whoami. Report agentId, displayName, project.
2. Check your worktree ↔ room alignment (see below) and realign if it drifted.
3. Discover peers — list_agents. Show the user who is online and where.
4. Show the comms cheat-sheet so you never mis-route.

Worktree drift check (do this at activation and after any cd)

project (which scopes your rooms) is captured when the agent process starts and does NOT follow you if you move to a different git worktree. Verify and realign:

basename "$(git rev-parse --show-toplevel)"   # your CURRENT worktree

If that differs from the project reported by whoami, call use_bridge with that name. DMs are global, so messaging still works even if your room drifts — this only keeps your room/lobby membership correct.

Critical Patterns

Comms Cheat-Sheet

# Claude Code / Codex (direct tools):
whoami
list_agents
send   to: "agent:<agentId>"   message: "<text>"     # global DM, durable
send   to: "room:<project>"    message: "<text>"     # your project's lobby only
read
use_bridge  bridge: "<project>"                       # realign rooms / share a room
set_name   name: "auth-reviewer"                      # memorable handle → reachable as agent:auth-reviewer
spawn_agent tool: "pi" name: "verifier" task: "..."   # open a new agent in a tab; it DMs you when up

# Pi (single tool, action=):
agent_bridge action=whoami
agent_bridge action=list_agents
agent_bridge action=send to="agent:<agentId>" message="<text>"
agent_bridge action=read
agent_bridge action=use_bridge bridge="<project>"
agent_bridge action=set_name name="auth-reviewer"
agent_bridge action=spawn_agent tool="pi" name="verifier" task="..."

Stable, memorable identity. The auto-generated agentId can be awkward to share. If the user gives you a name (or asks you to pick one), call set_name — it sets your displayName AND makes you reachable as agent:<name> (a stable DM alias on top of your agentId). Use a unique name; two agents sharing one would both receive its DMs.

Your DM subject (what wakes you): bridge.dm.<agentId> (claude-code-<ppid> for Claude, pi-<pid> for Pi). Under cmux, your displayName includes the surface name (e.g. Claude Code @ review) so instances are distinguishable.

Spawning a new agent (spawn_agent)

Launch a brand-new agent in a fresh terminal tab that gets on the bridge by itself and reports back to you. Use it when the user says e.g. "crea un agente de pi para que verifique X".

spawn_agent  tool: "pi"|"claude"   name: "test-verifier"   task: "verify the login flow"
# Pi:  agent_bridge action=spawn_agent tool="pi" name="test-verifier" task="verify the login flow"

What it does:

1. Detects the terminal host — a capability probe checks pane controllers before the emulator (cmux → tmux → zellij → plain emulator). This ordering matters: cmux runs on top of ghostty, so TERM_PROGRAM=ghostty and CMUX_SOCKET_PATH coexist; checking the emulator first would wrongly conclude "can't open a tab".
2. Opens the tab and launches the agent with a one-line startup prompt telling it to: activate the bridge, set_name "<name>", DM you to confirm it's active, then do task.
3. Graceful fallback — on a plain emulator (or if the spawn fails), it does NOT fail silently: it returns the exact command for the user to paste into a new tab. The command is identical to what it would have run itself.

After calling spawn_agent, wait for the new agent's confirmation DM — read to catch its "<name> online, ready" message, then coordinate the task over the bridge.

Optional fallback — application-level "Roll Call"

list_agents is the primary, reliable presence source. Only if you suspect the roster is stale, probe manually: send to: "room:<project>" message: "WHO_IN? from=<myAgentId>", then read the HERE ... DM replies (dedupe by id, exclude your own echo). If you RECEIVE a WHO_IN?, reply by DM to agent:<requesterId> with your identity.

Verification

• You reported your own agentId and confirmed your room matches your git worktree.
• list_agents shows live peers across projects.
• A DM to agent:<id> reaches the peer and wakes them; you read the reply.