Session coordination

The pi-intercom extension adds direct 1:1 messaging between Selesai sessions on the same machine. You can send context, ask questions, or delegate work from one named session to another without leaving the terminal.

Bundled with Selesai

Loaded automatically with Selesai; no per-extension npm install is required.

Manifest entry

./pi-intercom/index.ts

Runtime surface

Mixed (commands, tools, shortcuts)

Setup and prerequisites

• This extension is bundled with Selesai. It is loaded automatically; you do not need to install it separately.
• Two or more Selesai sessions must be running on the same machine.
• Intercom requires a local-only broker process. The broker auto-spawns on first use.
• Sessions must be named (or the extension provides a fallback alias) so other sessions can target them.
• Requires the TUI for overlay input. Non-interactive sessions can still send and reply via the intercom tool.
• Can be disabled with enabled: false in ~/.selesai/agent/intercom/config.json.

What it sets up

• Registers the /intercom slash command and the Alt+M shortcut to open the session list overlay.
• Registers the /alias slash command to set the current session alias from the CLI.
• Registers the intercom tool for agent-driven session discovery, sends, asks, and replies.
• Registers a native contact_supervisor tool when pi-subagents supplies child bridge metadata (SELESAI_SUBAGENT_ORCHESTRATOR_TARGET, SELESAI_SUBAGENT_RUN_ID, SELESAI_SUBAGENT_CHILD_AGENT, SELESAI_SUBAGENT_CHILD_INDEX).
• Starts a local broker on demand and publishes presence (name, cwd, model, status, context usage) for connected sessions.
• Supports optional restart-stable session IDs, cwd-scoped discovery, and bounded queued delivery for recently disconnected named sessions.

What you can configure

Intercom reads a single config file for broker command, args, confirmation, status suffix, and enable flags.

Configuration locations and precedence

1. Intercom config
   ~/.selesai/agent/intercom/config.json
   Only config file; no project layer.

Settings

Key / path	Type, default, and values	Description
brokerCommand	string Default: "npx"	Command used to spawn the broker process.
brokerArgs	string[] Default: ["--no-install", "tsx"]	Arguments passed to brokerCommand before the broker script path.
confirmSend	boolean Default: false	Require confirmation before non-reply sends in interactive sessions.
enabled	boolean Default: true	Enable or disable intercom entirely.
replyHint	boolean Default: true	Show a reply hint in incoming messages.
status	string Default: (not set)	Optional custom status suffix appended to automatic lifecycle status.

Command, tool, and shortcut controls

Key / path	Description
ask / reply tools	Send messages or replies between named local sessions.

Source evidence

• src/extensions/pi-intercom/config.ts

What you can do

• Send a fire-and-forget message with intercom({ action: "send", to: "worker", message: "..." }).
• Ask a blocking question with intercom({ action: "ask", to: "planner", message: "..." }); the reply comes back as the tool result with a 10-minute timeout.
• Reply to the most recent inbound ask with intercom({ action: "reply", message: "..." }). During a turn triggered by an inbound ask, a non-reply send to a different target is refused, so a guessed parent/root CWD cannot receive an accidental reply.
• List pending asks with intercom({ action: "pending" }) or check broker and session status with intercom({ action: "status" }).

Commands, tools, and shortcuts

Command / shortcut	Description
/intercom	Open the session list overlay.
/alias <name>	Set the current session alias (/alias menu prompts for one).
Alt+M	Open the session list overlay.
intercom({ action: "list" })	List connected local sessions.
intercom({ action: "list-cwd" })	List connected sessions in the same working directory.
intercom({ action: "send", to, message, attachments? })	Send a message immediately.
intercom({ action: "ask", to, message })	Send a message and block until the recipient replies.
intercom({ action: "reply", message, to? })	Reply to the current or single pending inbound ask.
intercom({ action: "pending" })	Show unresolved inbound asks.
intercom({ action: "status" })	Show connection status and active session count.
contact_supervisor({ reason, message?, interview? })	Subagent-only tool to contact the delegating supervisor session. Reasons: "need_decision", "interview_request", "progress_update".

Message attachments

You can attach snippets or files to a send:

intercom({
  action: "send",
  to: "worker",
  message: "Here is the fix:",
  attachments: [
    { type: "snippet", name: "auth.ts", language: "typescript", content: "..." }
  ]
})

Limits and safety

• Same-machine only. The broker uses restricted Unix-domain runtime files on macOS/Linux and opt-in authenticated localhost transport on Windows; there is no remote transport.
• Broker frames are size-bounded, connections are rate-limited, and stable IDs include local trust metadata; stable names are coordination identifiers, not an authentication boundary.
• Only sessions that have successfully registered with the broker appear in the list.
• ask blocks the calling agent for up to 10 minutes. If no reply arrives, the tool errors.
• reply without to only resolves a single pending ask. With multiple pending asks, specify to or inspect them first.
• Incoming messages are stored in the session history; there is no separate inbox or transcript.
• Attachments are included in the agent-visible body text; the TUI compose overlay does not yet provide attachment UI.
• Supervisor replies through contact_supervisor are scoped to the exact parent session id; other Selesai sessions do not receive them.

Source evidence

Selesai version: 0.10.0

• Intercom source
• README mention