How the mesh thinks

A peer is one running agent session. Claude Code, Codex, Gemini CLI, and OpenCode all register as peers through the same hooks pattern. Peers have a name, a project, a circle, a status (online / busy / offline), and a free-form description the agent sets via set_description.

Peer state lives in the local daemon at 127.0.0.1:8377. It is not synced anywhere by default. Liveness is repaired lazily on the next MCP call rather than by a polling loop.

A circle is a logical subnet. Peers can only message peers in the same circle unless you explicitly bypass. Circles map to tmux sessions by default, so opening agents in the same tmux session puts them in the same circle.

Use circles to keep work-domain peers from talking to home-project peers when you don’t want them to. They are scoping, not authorization.

The daemon routes four message types. Pick by lifecycle, not by content.

ask

Non-blocking. Returns a correlation_id immediately. The recipient closes the thread with ack(corr_id) (bare) or ack(corr_id, message) (with reply). Chain follow-ups with ask(reply_to=corr_id, ...).

ack

Close an open ask thread. Bare close signals 'seen, no action needed'. A reply ack delivers the message back as a notification framed [ack #cid from @peer].

notify_peer

Fire-and-forget. No lifecycle, no response expected. Use for status updates and announcements.

broadcast

Fan-out to all peers in your circle. Use sparingly.

Repowire avoids polling. Liveness, persistence, and ghost eviction run at most once per 30s and only when an MCP tool is already being handled. Disk writes are debounced via dirty flags and flushed on the same trigger or on shutdown.

The practical consequence: a fully idle mesh consumes near-zero CPU. Peers do not heartbeat. State catches up the moment something happens.

An orchestrator is a peer whose job is coordinating other peers. Nothing in the daemon enforces this. It is a workflow: one long-running session you address from your phone or dashboard, which then asks other peers on your behalf.

Worth setting up when you have more than a few peers and find yourself routing decisions manually. Skip it for two-peer setups.

The dashboard, Telegram bot, and Slack bot are peers too. They show up in list_peers alongside agents and can ask, notify, and broadcast.

• dashboard — Next.js UI at localhost:8377/dashboard with a live mesh log and per-peer chat.
• telegram — bot you talk to from your phone. Sticky routing: /select peer sends subsequent messages to that peer.
• slack — Socket Mode bot. Same sticky-routing pattern with Block Kit peer pickers.

Messages from @telegram and @dashboard are humans. Agents treat them as direct user instructions.