| name | bridgey |
| description | This skill should be used when the user asks to "set up bridgey", "check bridgey status", "add a bridgey agent", or "scan the tailnet for bridgey". Lifecycle surface for the bridgey A2A daemon — first-time setup, health dashboard, remote-agent registration, and Tailscale mesh discovery. |
| version | 0.3.0 |
bridgey
Single lifecycle skill for the bridgey A2A communication daemon. Bridgey turns each Claude Code instance into both an A2A client and server, with optional Tailscale mesh discovery and Discord/webhook transport adapters.
When to use
Activate on any bridgey daemon operation: first-time install, health checks, registering remote peers, enabling tailnet discovery, or troubleshooting connectivity. The daemon's tools (send, list_agents, get_inbox, status, configure_agent, tailscale_scan, etc.) are always available via MCP — this skill covers the operator-facing lifecycle workflows that compose those tools.
Architecture quick-recall
Two processes per host:
- Daemon (Fastify HTTP, persists across sessions) — handles the A2A protocol, transport registry, peer storage at
~/.bridgey/. Pidfile at /tmp/bridgey-${USER}.pid.
- Channel Server (stdio, lives with the CC session) — pushes inbound messages to Claude. Each session registers under
${basename(cwd)}-${pid} (override via BRIDGEY_AGENT_NAME).
The daemon is a router, not an A2A agent — its config.name is a display label, not addressable. Multiple concurrent sessions per host are supported.
Claude Code <-stdio-> Channel Server <-HTTP-> Daemon <-A2A/HTTP-> Remote Daemons
|
Transport Adapters (Discord, etc.)
Workflows by intent
| User says... | Read |
|---|
| "set up bridgey", "first time install", "configure bridgey" | references/setup.md |
| "bridgey status", "is it running", "show agents" | references/agents.md (Status section) |
| "add agent", "connect to ", "register remote agent" | references/agents.md (Add Agent section) |
| "tailscale setup", "enable mesh discovery" | references/tailscale.md (Setup section) |
| "scan tailnet", "find peers", "discover agents" | references/tailscale.md (Scan section) |
Read the reference file before starting the workflow — each contains the full step procedure with config schemas, troubleshooting, and container-deployment notes.
Cross-cutting rules
Config location. ~/.bridgey/bridgey.config.json survives plugin updates. Do not edit manually unless the user asks — use the workflows in references/setup.md and references/agents.md. The daemon picks up changes on next request, or restart with the stop/start commands documented in those references.
Token discipline. Bearer tokens are prefixed brg_ and generated via crypto.randomBytes(32).toString('hex'). Store secrets in pass (pass insert bridgey/agent-name-token) — never hardcode in committed config. Generate inline:
node -e "console.log('brg_' + require('crypto').randomBytes(32).toString('hex'))"
Bind modes. Default localhost is most secure. Use 0.0.0.0 only when Docker or Tailscale exposure is needed; pair with trusted_networks CIDRs to allow token-free access from known ranges. Canonical CIDR table (the one home for these values):
| Network | CIDR |
|---|
| Tailscale | 100.64.0.0/10 |
| Docker bridge | 172.16.0.0/12 |
| Docker overlay / alt bridge | 10.0.0.0/8 |
Container deployments. See references/setup.md §Container / headless deployment notes — the one home for bind, trusted-CIDR, credential-mount, and inter-container DNS requirements.
Discovery boundaries.
- Local agents (same host): auto-discovered via
~/.bridgey/agents/ file registry
- Remote agents: configured via
references/agents.md Add Agent flow OR auto-registered via Tailscale scan when references/tailscale.md Setup is complete
Daemon health quick-check
For a one-line probe outside the full status dashboard:
curl -s http://localhost:8091/health | jq .
Local port map: hub daemon 8091; persona spoke daemons 8092–8103. Container deployments use the Tailscale IP or Docker host. Expected response includes {"status":"ok",...}. Failures point to ~/.bridgey/daemon.log for diagnostics.
Manual daemon control
Canonical daemon lifecycle — every start/stop/restart step elsewhere in this plugin points here.
The bridgey-hub.service systemd user unit runs the daemon (start-on-boot, restart-on-crash) — it is not tied to a Claude Code session.
Preferred — systemd:
systemctl --user restart bridgey-hub.service
systemctl --user status bridgey-hub.service
cat ~/.bridgey/daemon.log
Fallback — raw node (no systemd unit, e.g. containers or ad-hoc runs). If dist/daemon.js is missing, build it first — this build incantation is stated only here:
cd ~/projects/markets/bridgey/apps/daemon && npm run build
node ~/projects/markets/bridgey/apps/daemon/dist/daemon.js stop
node ~/projects/markets/bridgey/apps/daemon/dist/daemon.js start \
--config ~/.bridgey/bridgey.config.json
Reference files
references/setup.md — first-time configuration walkthrough (interactive 6-step flow, security token generation, container/headless notes)references/agents.md — status dashboard + add-remote-agent procedure (connectivity verification, Agent Card fetch, mutual-registration reminder, troubleshooting 400/401/403/429 responses)references/tailscale.md — Tailscale mesh setup + scan-results display (CIDR allowlist, tailscale.config.json schema, peer discovery loop)
