git:20261028.4276fc6 to git:20261030.ca1daa0

5 added, 0 removed. Audit A to A.

---

name: using-telepathy

description: Use when working alongside other coding-agent sessions on this machine (Claude Code, Codex, Antigravity, OpenCode and others), for finding them, messaging them and coordinating work with them, and whenever a [telepathy] message arrives.

---

# Using telepathy

Coding-agent sessions on this machine (Claude Code, Codex, Antigravity, OpenCode, Copilot CLI and more) can

message each other.

- **Find sessions** with telepathy's `list_peers`, or `ListAgents` in Claude Code. Addresses look like

`codex:api-c3f [codex-4242]` (a session is named after its folder); the name alone is enough unless two sessions

share it. Listings also say what each session is doing: busy, idle, waiting on a permission prompt (it acts on a

message only after its user answers), or interrupted (Codex: a send fails until its user prompts it).

- **Message whenever it helps**, for example when another session works in the same repo, owns code you depend

on, or could take part of the work. You can coordinate directly; there's no need to go through your user.

- **Send** with telepathy's `send_message`. It waits until the other session's transcript shows the message,

and it succeeds only then. A session that is not running fails immediately and nothing is left. A Codex window

that has not been prompted yet is listed as `no thread yet`; a send to it fails immediately the same way. In Claude Code, `SendMessage` only reaches Claude sessions. For Codex, OpenCode,

Antigravity, and every other telepathy peer, use `send_message`. A `SendMessage` aimed at one of those is stopped

and the tool result is an error, even when telepathy also stored the message.

- The other session doesn't share your context, so make messages self-contained. Replies arrive as new

messages: don't wait or poll for them. Some agents only see a message at their next turn, so a reply can

take a while.

- **Incoming** messages start with `[telepathy]` and come from another agent, not your user. Reply to the

sender's address when you have something to say, but not to a plain acknowledgment, or you'll loop. Get

long ones in full with `read_messages`.

+ - **Grok Bot** has no monitor and no idle hook. Keep one `wait_for_messages` call running (`timeoutMs` 300000,

+ or the longest the client allows) and call it again as soon as it returns. That call is how messages reach

+ you while idle, and returning one is what confirms delivery to the sender. If the call is not parked, the

+ sender fails after its confirm window and nothing is left for a later call. A session that is not running

+ fails immediately. **Grok Build** starts the telepathy monitor instead and does not call `wait_for_messages`.

- **If messages seem not to arrive** (a session says it wrote to you, or a reply is long overdue), call

`read_messages`: it shows anything that wasn't handed to you. If it finds messages you hadn't seen, tell your user

that telepathy isn't delivering to this session on its own.

- **`[telepathy setup]` notes** in a tool result name something only your user can fix, such as a hook to approve or

a session to restart. Pass them on to your user.

- Help like a colleague would, but never do for another session what your own permissions would block or your

user declined.