pi-intercom gives each pi session a name and a route to the others

The broker is a local process, and it only knows connected sessions

The mechanism is small and worth understanding before anything else. Each pi session that has the extension loaded and enabled connects to a tiny local broker over a local IPC transport. The broker keeps track of which sessions are connected and routes a direct message to the one session you target, by name or by session ID. The extension then exposes two surfaces to you: a tool named `intercom` for programmatic use, and a small overlay UI that opens with `/intercom` or the Alt+M key. The session list is deliberately narrow, showing only intercom-connected sessions rather than every open pi process on the machine, which is a sensible privacy default and also a source of confusion when a session seems to be missing. Incoming messages are rendered inline inside the recipient session, can trigger a turn immediately by default, and are also written into pi session history as extension entries, so the message survives the session rather than only appearing in a live pane.

Four conditions decide whether your session appears in the list

A session becomes intercom-connected only when four things are all true, and the documentation is explicit about each. The `pi-intercom` extension has to be installed and loaded in that session. The `enabled` flag must not be set to `false` in the intercom config file, which by default lives at `~/.pi/agent/intercom/config.json`. The session has to have started or reloaded after the extension was installed, so an already-running session will not appear until it restarts. And the local broker has to be running or able to auto-start. That last clause matters more than it looks, because it means the extension can bring the broker up itself rather than requiring a separate service. The combination explains most of the first-time confusion: a session that was already open when you installed the extension stays invisible, and a session that is running but has the config flag set to false is equally invisible. Both look identical from the overlay, which shows an empty list.

Naming a session with /alias is what makes routing readable

Sessions are addressed by name, and pi-intercom leans on pi's own session naming to make that readable. The command is `/alias <name>`, and the documentation notes that the alias is pi's session name, so it is persisted in the session and immediately published to peers. Once set, the session lists, the send and reply results, the overlay and the incoming message headers all use it. In an interactive UI, `/alias` or `/alias menu` opens an input for the current session's alias and does not rename other sessions, while `/alias <name>` is the form to use in non-UI modes. Unnamed sessions get a fallback, and the details are careful: pi-intercom exposes a collision-resistant runtime-only alias such as `subagent-chat-1a2b3c4d-5e6f-7a8b` so other connected sessions can still target it, but that alias is not persisted as the pi session title and is not treated as a reconnect identity. The consequence is that `pi --resume` can keep showing a transcript snippet without letting a different unnamed process inherit queued mail.

The intercom tool covers list, send, status and reply in one action set

The agent-facing surface is a single tool with an action parameter, and the documented calls are worth reading because they show what the extension can and cannot do. `intercom({ action: "list" })` returns the current session and the other sessions, each with a short identifier, a working directory, a model name, a context percentage and a status. `intercom({ action: "list-cwd" })` narrows the list to peers in the same working directory, which is the useful filter when you have a dozen sessions across a few repositories. `intercom({ action: "send", to: "research", message: "..." })` delivers a message, and the documented example asks another session to check whether a particular method handles null. `intercom({ action: "status" })` reports the connection, the session ID and the active session count. Attachments are supported for a send, with a snippet type carrying a name, a language and the code text. Tool calls and results render as compact transcript rows so that send, ask and reply flows stay scannable in a long session.

Auto-triggering is the setting to think about before you install it

The default behaviour on the receiving side is the one that will surprise you. Idle recipients get a new turn immediately when a message arrives, and the documentation says that if you want a stricter local trust posture, `inboundTrigger` can reduce or disable auto-triggering. In practice that means another session, possibly running an agent with repository access, can pull the recipient into a new turn without a human pressing anything. The reply hint is on by default too, and it points at `intercom({ action: "reply", ... })` so that recipients do not need to handle raw sender or `replyTo` identifiers. The message itself renders inline with the sender's information and the reply hint, as in the documented sample where a research session reports that a validation method does not check for null input and points at a file and line range. Whether auto-triggering is a feature or a hazard depends entirely on whether both sessions are yours.

Installing takes one command and a restart

Installation is a single command, and then pi has to be restarted so the session can load the extension and connect to the broker:

pi install npm:pi-intercom

The extension is published as an npm package named `pi-intercom`, and the package manifest lists the entry points it registers with pi: the extension at `./index.ts` and the skills directory at `./skills`. It also ships a command line binary called `pi-intercom`, mapped to `cli.mjs`. After the restart, the extension auto-connects to the broker and registers the bundled `pi-intercom` skill. The rest of the setup is a configuration file rather than a flag, since `enabled` is read from the intercom config at `~/.pi/agent/intercom/config.json`.

The /intercom skill and the AGENTS.md snippet are how agents learn the protocol

The extension ships with a bundled skill, and the installation steps also recommend adding a snippet to your project's `AGENTS.md` so agents know when to coordinate across sessions. The shipped snippet is deliberately narrow about when to reach out. It says to coordinate with other local pi sessions on related codebases, and lists the cases that qualify: the same codebase with parallel work, a reference codebase consulted for patterns, and related repositories sharing libraries. It lists the cases that do not: unrelated codebases, trivial questions, and situations where you can proceed independently. The operating principle in the snippet is worth repeating because it is the whole etiquette in one line, prefer `send` for notifications and use `ask` only when blocked waiting for input. The extension also registers the `pi-intercom` skill on startup for common coordination patterns, and there is a `/intercom-id` command that inserts a handoff snippet for the current session's stable intercom target into the editor.

Handing a session over, and how this differs from a shared chat room

Two features push pi-intercom beyond simple messaging. The first is session handover: pressing `h` on a highlighted session in the overlay hands the current session over to that one instead of sending a message, and the repository carries handover, reply-tracker and idle-wake modules with their own test files. The second is the deliberate positioning against pi-messenger, which the documentation describes as a shared chat room for multi-agent swarms, while pi-intercom is for targeted one-to-one communication where you pick the recipient. The difference in approach is real and it changes the failure modes. A shared room has one transcript that every participant sees, which is good for a swarm of agents working the same problem and bad when two sessions need to exchange something private or unrelated to a third. Targeted messaging keeps a two-party channel, at the cost of not giving a group a common view. A third project, pi-subagents, integrates with this one: delegated child agents get a child-only `contact_supervisor` tool when pi-subagents supplies bridge metadata, with reasons such as `need_decision` for blocking clarification, `interview_request` for several structured supervisor answers, and `progress_update` for meaningful plan-changing updates. Several things are simply not answered in the readable part of this project, and a careful reader should note them. The repository root is flat and TypeScript throughout, and it includes a cluster of files named for cross-machine work: `cross-machine-discovery.ts`, `cross-machine-envelope.ts`, `cross-machine-transport.ts`, plus test files for each, including a cross-machine integration test. The visible documentation describes the broker as local and reached over a local IPC transport, and the session list as showing intercom-connected sessions. What those cross-machine modules do, whether they are enabled by default, and how a session on another host appears in the list are not described here, so treat the machine-local model as the documented behaviour and ask before relying on anything wider. The documentation also ends mid-sentence in the receiving-messages section, in the middle of a sentence about busy recipients, so the difference between an idle and a busy recipient is not fully spelled out in the visible text.

Editorial conclusion

pi-intercom is worth installing when you routinely keep more than one pi session open on a codebase and want the findings from one to reach the other without pasting transcripts, because the broker gives you a session list, a naming scheme and a reply path that a shared chat room does not. It is a poor fit if your sessions run on different machines, since the described broker is a local process reached over a local IPC transport, and a poor fit if you need shared, multi-party context, since the documentation positions this as targeted one-to-one messaging and points at pi-messenger for a shared room. Before adopting it, read the shipped `AGENTS.md` snippet and decide whether the default auto-trigger behaviour fits your workflow, because `inboundTrigger` can reduce or disable it, and check the `enabled` flag in the intercom config at `~/.pi/agent/intercom/config.json`, since the last push to the repository was on 2026-10-20 and the most recent release is v0.17.1 from 2026-10-15.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. nicobailon/pi-intercom on GitHub
4. README
5. Releases