nicobailon/pi-intercom

Pi Intercom – Quick‑look

What it is – A lightweight extension for the Pi AI‑agent platform that lets separate Pi sessions running on the same computer talk to each other one‑on‑one. It adds a small UI (Alt + M or the /intercom command) and a programmable tool (intercom) so a user or an autonomous agent can list sessions, send messages, ask questions (blocking until a reply), reply, hand‑off work, or cancel messages.

Why it matters – When you split a complex task across multiple Pi agents (e.g., a planner and a worker, or a child sub‑agent and its supervisor) you need a reliable way to pass context, ask for clarification, or hand over the session state. Pi‑intercom provides that without leaving the local machine or relying on an external chat service, keeping the communication fast, private, and tightly integrated with Pi’s turn‑based execution model.

Key features

• Local broker – each session connects to a tiny IPC broker that tracks session IDs, aliases, and routes messages directly.
• Aliases & IDs – sessions can be named (/alias <name>) or get a collision‑resistant fallback alias, making targeting easy.
• Tool actions – list, list‑cwd, send, ask, reply, handover, cancel, status, etc., all callable from a Pi script.
• Inline rendering – incoming messages appear in the transcript, can trigger an immediate turn, and are stored as extension entries.
• Blocking ask – ask blocks the sender (default 10 min timeout) until the receiver replies, enabling true back‑and‑forth without losing context.
• Safety knobs – inboundTrigger, busyDelivery, confirmSend, and timeout settings let you control when messages interrupt a running turn.
• Mailbox for disconnects – short‑lived sessions can still receive replies after a reconnection; unnamed sessions get only runtime aliases.
• Integration with pi‑subagents – child agents get a contact_supervisor tool for supervisor‑only escalations.

Typical workflow

1. Start two Pi terminals and give them aliases, e.g. planner and worker.
2. The planner sends a task description to the worker.
3. The worker asks for clarification; the planner’s reply is injected back into the same turn.
4. The worker reports completion with another ask; the planner can issue the next task.

Installation

pi install npm:pi-intercom   # registers the extension and skill
# restart Pi to auto‑connect to the broker

Add a short description to AGENTS.md (shown in the README) to help other agents know when to use the tool.

When you’d use it

• Coordinating multiple agents on the same codebase.
• Delegating work from a high‑level planner to a specialized worker.
• Escalating a sub‑agent’s question to its supervisor.
• Handing over a session to another Pi process (e.g., moving from a local run to a remote adapter).

When it’s not needed

• Simple single‑session work.
• Communication across machines (Pi‑intercom is local‑only; use other networking tools for that).

Overall, Pi‑intercom is a focused, low‑overhead solution for intra‑machine, 1‑to‑1 messaging between Pi AI‑agent sessions, enabling richer multi‑agent orchestration without leaving the Pi ecosystem.