Reference

MCP tools

Every agent in the mesh exposes the same set of MCP tools through the repowire server. Tool calls go to the local daemon over HTTP; the agent never sees daemon internals. Names are stable and used identically across Claude Code, Codex, Gemini CLI, and OpenCode.

ask

ask(peer_name: str, query: str, reply_to: str | None = None, circle: str | None = None) -> str

Open a non-blocking ask thread. Returns a correlation_id immediately. The recipient closes the thread with ack; the daemon routes the close back as a notification framed [ack #cid from @peer].

Pass reply_to to chain a follow-up: the prior thread closes and a new one opens referencing it. Pass circle only when two peers share a name in different circles.

ask("project-b", "What API endpoints do you expose?")
# returns "ask-c1a1c7dd"

ack

ack(correlation_id: str, message: str | None = None) -> str

Close an open ask. Bare ack(cid) signals “seen, no action needed.” A reply ack(cid, message) closes the thread and delivers the message back to the original asker. Replies always reach the asker regardless of circle, because the thread was established at ask-time.

ack("ask-c1a1c7dd")
ack("ask-c1a1c7dd", "we expose /health, /peers, /ask, /ack")

notify_peer

notify_peer(peer_name: str, message: str, circle: str | None = None) -> str

Fire-and-forget. No lifecycle, no expected response. Returns a synthetic notif-XXXXXXXX ID for client-side tracking, not a thread you can close. Use for status pings and announcements.

The special peer telegram routes to the user’s phone. The dashboard already sees agent turns; you do not need to notify it.

notify_peer("telegram", "deploy finished, green across CI")

broadcast

broadcast(message: str) -> str

Fan out to every online peer in your circle. No correlation, no reply. Use sparingly; treat it as a soft interrupt for everyone in scope.

broadcast("rebasing main, hold pushes for ~5 min")

list_peers

list_peers(show_offline: bool = False, include_self: bool = False) -> str

Returns a TSV with columns: peer_id, name, project, circle, role, status, path, machine, description, backend. Defaults to online + busy peers and hides the caller. Pass show_offline=True for the full registry; pass include_self=True when an orchestrator needs its own row.

whoami

whoami() -> str

Returns the caller’s own TSV row. Useful when an agent needs to know which display name it is registered under (display names get suffixed on collision: repowire, repowire-2).

set_description

set_description(description: str) -> str

Update the free-form description visible in list_peers. Call this at the start of a task so peers can see what you are working on without asking.

set_description("rebuilding docs slice B")

spawn_peer

spawn_peer(path: str, command: str, circle: str = "default", message: str | None = None) -> str

Spawn a new agent session in a project directory. The command must exactly match an entry in daemon.spawn.allowed_commands in ~/.repowire/config.yaml; spawn is off by default until you allowlist something.

The spawned agent self-registers via its SessionStart hook within a few seconds. The message seeds first-turn context. Codex requires it (or a default) to fire its hook; other backends treat it as an opening prompt.

kill_peer

kill_peer(peer_identifier: str, circle: str | None = None) -> str

Terminate a peer by name or peer_id. Used by orchestrators to reclaim slots when a session is stuck or done. The daemon marks the peer offline reliably and attempts to reap its tmux pane (best-effort; verify with tmux list-windows and follow up with tmux kill-window if the pane survives).