pi-intercom plugin
pi-intercom links pi sessions on one machine for one-to-one messages between agents or through the Alt+M shortcut.
- 627 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- An incoming message can trigger an agent turn by default, so sessions can receive instructions from each other without a human in the loop.
Install
Manual install
pi install npm:pi-intercomThe first Install command in the README. pi must be restarted afterwards.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- An incoming message can trigger an agent turn by default, so sessions can receive instructions from each other without a human in the loop.
This is third-party code. Review the repository files before installing.
What it does
pi-intercom, an extension for the pi agent, connects open sessions through a local broker. A user picks a session with `Alt+M` or `/intercom` and sends it context, findings or a request. An agent does the same with the `intercom` tool: lists sessions, sends messages and waits for a reply. Messages arrive directly in the recipient session and are stored in pi history. The `/alias <name>` command names a session. With pi-subagents, a child agent gets a `contact_supervisor` tool with reasons `need_decision`, `interview_request` and `progress_update`. A bundled `pi-intercom` skill describes common patterns.
Who it is for. pi users who keep several sessions with different roles: one researches, one executes, one reviews.
Good fit when
- Context found in a research session is handed to an execution session.
- An agent in parallel work on the same codebase tells its neighbor it is done.
- A child agent stalled at a fork and asks the supervisor for a decision.
- A session is handed over to another one with the `h` key.
- A library in another repository is consulted through the session working in it.
Not a fit when
- Sessions share no codebase and questions are trivial.
- An agent can proceed alone without waiting for another session's reply.
- A strict local policy forbids auto-triggering a turn on an incoming message.
Example request
List connected intercom sessions and send my findings summary to the api-worker session without waiting for a reply.Limitations
The extension works only with pi and only for sessions on one machine through a local broker. By default an incoming message can trigger a turn in the recipient session, so on a strict trust model configure `inboundTrigger`. The list shows only sessions where the extension is loaded and enabled, not every pi process. Unnamed sessions get a temporary alias that is not persisted. pi must be restarted after installation. The related pi-messenger project covers a shared chat for agent swarms.
How to disable. Set `enabled: false` in `~/.pi/agent/intercom/config.json` or remove the extension and restart pi. The broker stops along with the sessions.
FAQ
How do I send a message manually?
Press `Alt+M` or type `/intercom`, pick a session with the arrow keys, write the text and press Enter. Escape cancels.
How is it different from pi-messenger?
pi-intercom links two chosen sessions one to one, while pi-messenger serves as a shared chat for agent swarms.
How do I name a session?
With `/alias api-worker`. The name is stored in the session and is immediately visible to other connected sessions.
When should an agent send and when ask?
The README advises `send` for notifications and `ask` only when work is blocked until a reply.
Where are messages stored?
In pi session history as extension entries, so they remain after a restart and appear when the session resumes.
Discussion
No questions or reviews yet.
Related
PluginsAn extension for the Pi agent (pi.dev): subagents and orchestration in the Claude Code style, a widget and JavaScript scripts. Not for Claude Code
A web app for the Pi coding agent: sessions survive restarts, teammates can join, and you can work from a phone with no cloud VM
Package for the Pi agent with an ask_user tool: the agent pauses and asks you when a decision cannot be made without a human.
Pi extension for background subagents: parallel delegation, a Manager, Lead and Agent chain and supervision in herdr
A Telegram bridge for the Pi coding agent: continue sessions from your phone and hand them back to the terminal
Personal Pi agent setup with four commands for plan, todos, execution and review, passing state through Markdown session files.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| pi-intercom (this card) | no | 627 | |
| pi-subagents | no | 1,449 | spawns child agents inside pi; pi-intercom links independent sessions and gives children a line to the supervisor |
| Pi Herdsman | no | 226 | manages a group of pi sessions; pi-intercom passes messages between chosen sessions |
README in short
The extension provides a tool and a small overlay for exchange between sessions. Incoming messages render inline in the session and are saved as extension entries.