nicobailon/pi-intercom

What it solves

Pi-intercom enables direct 1:1 communication between multiple active AI sessions on the same machine. It solves the problem of fragmented context when running parallel sessions (e.g., one for research, one for execution, and one for review), allowing users and agents to share findings, request decisions, or coordinate tasks without manually copying and pasting information between windows.

How it works

Each enabled session connects to a local broker via IPC transport. The broker tracks connected sessions and routes messages based on session names or IDs.

• For Users: An overlay UI (accessed via Alt+M or /intercom) allows for selecting a target session and composing messages.
• For Agents: A dedicated intercom tool allows agents to list active sessions, send non-blocking messages (send), or send blocking requests (ask) that pause the agent's turn until a reply is received.
• Subagent Integration: When used with pi-subagents, child agents receive a specialized contact_supervisor tool to escalate decisions, request structured interviews, or provide progress updates to their supervisor session.

Who it’s for

Developers and power users of the Pi ecosystem who run multiple concurrent AI sessions to handle complex, multi-stage workflows or orchestrate a team of specialized agents on a single machine.

Highlights

• Blocking vs. Non-blocking: Supports send for notifications and ask for synchronous requests that return the answer as a tool result.
• Session Awareness: Agents can list all active sessions or filter for peers working in the same directory.
• Subagent Escalation: Specialized tools for child agents to communicate with supervisors using specific reasons like need_decision or interview_request.
• Contextual Replies: Incoming messages include "reply hints" that provide the exact tool call needed to respond, simplifying the agent's workflow.
• Local Broker Architecture: Uses a lightweight local broker to manage routing and a bounded in-memory mailbox for temporarily disconnected named sessions.