Pi Intercom

Pi Intercom Skill

Use this skill when you need to coordinate work across multiple pi sessions running on the same machine. Pi-intercom enables direct 1:1 messaging between sessions for delegation, context sharing, and collaborative workflows.

When you are supervising pi-subagents, delegated child agents can escalate to you via contact_supervisor if pi-subagents supplied child bridge metadata. This skill covers how to handle those orchestrator-side escalations.

When to Use

• Task delegation: Split work between a planner session and worker sessions
• Context handoffs: Send findings from a research session to an execution session
• Clarification loops: Worker asks questions, planner answers, work continues
• Multi-session workflows: Coordinate between specialized sessions (frontend/backend, research/implementation)
• Cross-codebase peer messages: Message an explicit live peer in another project, or open a visible Herdr project pane when a long-lived conversation is needed

Core Patterns

Pattern 1: Planner-Worker Delegation

The most common pattern. One session holds the big picture, others do hands-on work.

Setup (in each session):

/alias planner   # Terminal 1
/alias worker    # Terminal 2

Planner delegates a task (fire-and-forget):

intercom({
  action: "send",
  to: "worker",
  message: "Task-3: Add retry logic to API client. Key files: src/api/client.ts. Ask if anything's unclear."
})

Worker asks for clarification (blocks until answer):

intercom({
  action: "ask",
  to: "planner",
  message: "Should I use exponential backoff or fixed intervals?"
})
// → Returns the planner's reply as the result

Worker reports completion:

intercom({
  action: "ask",
  to: "planner",
  message: "Task-3 complete. Added exponential backoff (100ms → 1600ms, max 5 retries). Ready for task-4?"
})

Pattern 2: Quick Status Check

Before sending, verify who's connected:

intercom({ action: "list" })
// → Shows all connected sessions with names, cwd, models, live status, and
//   current Herdr workspace/tab/pane (or explicit not-hosted/unavailable state)

Pattern 3: Reply Naturally

When responding to an inbound ask, prefer reply instead of reconstructing raw IDs:

// In the turn triggered by the ask:
intercom({
  action: "reply",
  message: "Use exponential backoff starting at 100ms."
})

// If replying later and there might be more than one pending ask:
intercom({ action: "pending" })
intercom({ action: "reply", to: "planner", message: "Use exponential backoff starting at 100ms." })

reply still preserves exact threading under the hood by sending the response with the original replyTo value.

Pattern 4: Broadcast to Multiple Workers

Send to multiple sessions in parallel:

const workers = ["worker-1", "worker-2", "worker-3"];
const task = "Check for null pointer exceptions in your assigned files";

// Fire-and-forget to all workers
workers.forEach(w => 
  intercom({ action: "send", to: w, message: task })
);

Pattern 5: Send with Attachments

Share code snippets, files, or context:

intercom({
  action: "send",
  to: "worker",
  message: "Here's the fix for the auth issue:",
  attachments: [{
    type: "snippet",
    name: "auth.ts",
    language: "typescript",
    content: `function validateUser(user: User | null) {
  if (!user) throw new Error("User required");
  return user.email?.includes("@");
}`
  }]
})

Pattern 6: Cross-Codebase Peer Messages

Use to alone to message any explicit live peer on the machine, even when it is in another codebase. Use cwd alone when there should be exactly one live peer in that repo. Use to plus cwd when the directory is a safety guard.

intercom({
  action: "ask",
  cwd: "/path/to/other-repo",
  to: "workbench-agent",
  message: "Which module owns workbench source slices?"
})

Only open a Herdr project pane when you need a durable visible peer session in that repo. For bounded work, prefer pi-subagents with an explicit cwd; the child can use contact_supervisor for owner decisions and regular intercom for explicit peer coordination.

intercom({
  action: "send",
  cwd: "/path/to/other-repo",
  openProjectPaneIfMissing: true,
  message: "Let's discuss the workbench API ergonomics in this repo."
})

If a live session already exists in that cwd, intercom reuses it. If multiple sessions are active there, pass to to select one by name or session ID.

Pattern 6b: Hand Over Your Session

When the user moves work to another session, handover summarizes this session (next task, decisions, files, current state, open questions) with the current model and sends it. The receiver acts on it like any inbound message. Pass the next task as message; targeting works exactly like send.

intercom({
  action: "handover",
  cwd: "/path/to/other-repo",
  openProjectPaneIfMissing: true,
  message: "Port the schema fix here and run the adapter tests"
})

Humans can run /handover <target> [next task] to review the summary in an editor before it is sent. /handover alone opens a picker for the target.

Pattern 7: Handle Subagent Escalations (Orchestrator Side)

When pi-subagents spawns a delegated child and supplies child bridge metadata, that child can reach you through contact_supervisor. You receive a formatted message that includes run metadata:

**From subagent-worker-78f659a3-1**

Subagent needs a supervisor decision.
Run: 78f659a3
Agent: worker
Child index: 0

Which API should I use?

Reply using reply:

// The reply hint in the incoming message will show the exact call:
intercom({ action: "reply", message: "Use the stable v2 API." })

This works because reply resolves the correct sender and message ID automatically.

Three types of escalations to expect:

When a subagent asks:

// In the turn triggered by the incoming ask:
intercom({ action: "reply", message: "Use exponential backoff, max 3 retries." })

When a subagent sends an interview request:

Read the rendered questions in the incoming message and reply with the exact ids in JSON. info questions are context-only and do not need response entries:

intercom({
  action: "reply",
  message: "```json\n{\n  \"responses\": [\n    { \"id\": \"api\", \"value\": \"Stable API\" },\n    { \"id\": \"constraints\", \"value\": \"Keep the public error shape unchanged.\" }\n  ]\n}\n```"
})

If you receive multiple pending asks from different subagents:

intercom({ action: "pending" })
// → Shows all unresolved inbound asks with sender, elapsed time, and preview

intercom({ action: "reply", to: "subagent-worker-78f659a3-1", message: "Use the v2 API." })

Important: Only sessions where pi-subagents supplied child bridge metadata get the contact_supervisor tool. Normal sessions use the regular intercom tool. If you see the formatted supervisor decision/progress update message, treat it as a contact_supervisor escalation. A subagent may use regular intercom for peer coordination, including peers in other directories, but owner decisions and new visible project panes should go through the supervisor.

Key Differences