using-telepathy git:20261030.ca1daa0A

Immutable. This exact content never changes and is served at /api/v1/blob/90aee07e50637f42.

---
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.