crosstalk

name	crosstalk
description	Inter-session pi messaging — structured user-turn delivery between pi sessions (orchestrator ↔ worker, peer ↔ peer) and from external triggers (shell scripts, CI hooks, cron, event systems) via the `pi-crosstalk` CLI. Use when one pi session needs to send a real user turn into another, when spawning worker pi sessions you want to steer or follow-up, or when wiring an external trigger into a running pi session. Triggers — "crosstalk", "pi-crosstalk", "PI_CROSSTALK", "talk_to_peer", "crosstalk_set", "send a message to another pi session", "orchestrator → worker pi".
compatibility	Requires the crosstalk pi extension loaded (ships with `pi-agent-extensions-extra`) and the `pi-crosstalk` Go CLI on PATH for out-of-session sends.
metadata	{"version":"0.1","author":"Re"}

Crosstalk — Inter-Session Pi Messaging

Crosstalk is a pi extension plus a standalone Go CLI (pi-crosstalk) that lets pi sessions exchange real user turns with each other and accept structured pokes from external triggers. Each pi session listens on its own unix socket under $XDG_RUNTIME_DIR/crosstalk/; receivers enforce ACLs locally; there is no central daemon.

Crosstalk is the structured way to inject input into a running pi session from another pi session or from outside it. Inbound messages land via pi.sendUserMessage() (or sendMessage() for meta items) with proper deliverAs semantics, so a message that arrives mid-turn becomes a queued follow-up or steer instead of colliding with the user's input line.

Off by default per session. A fresh pi session has crosstalk disabled — no socket, no registry entry, not discoverable. The user (or an env var) opts in.

Loaded in a non-pi harness? This skill is reference material in any harness that surfaces it (pi, Claude Code, etc.). The slash commands and pi.sendUserMessage semantics described below only exist inside a running pi session with the crosstalk extension loaded; an agent reading this skill from another harness can guide the user or write shell/CLI invocations of pi-crosstalk, but cannot itself act as a crosstalk peer.

When to Use Crosstalk

Reach for crosstalk when all of the following are true:

• The recipient is a running pi session
• The crosstalk extension is loaded and enabled in that session
• You want the receiver's LLM to see a tagged user turn it can parse, with proper streaming-aware delivery (auto-routes to deliverAs: "followUp" if the recipient is mid-turn)
• You want ACL enforcement (the receiver decides whether to accept, based on parent / children / peers / external bucket classification)

Fall back to a keystroke-injection mechanism (any tool that writes directly to the recipient's PTY) only when crosstalk isn't enabled or you genuinely need raw keystrokes (TUI nav, partial input, control keys).

Orchestrator → Worker Spawning Recipe

The headline pattern: spawn a worker pi pre-configured to accept messages from its orchestrator. The env-var surface is what makes this clean — set them however you spawn subprocess pi sessions (shell env, a session manager, a systemd unit, a launch script).

# In the orchestrator session, make sure crosstalk is on and you have a handle:
#   /crosstalk
#   /crosstalk handle my-orch

# Spawn a worker pi with crosstalk pre-wired as a child of my-orch.
# Substitute your usual pi-spawning command in place of plain `pi` below.
PI_CROSSTALK=1 \
  PI_CROSSTALK_ROLE=worker \
  PI_CROSSTALK_PARENT=my-orch \
  PI_CROSSTALK_HANDLE=my-orch-wkr-build \
  pi @/tmp/build-prompt.md

The worker comes up with:

• Crosstalk enabled (PI_CROSSTALK=1)
• Role worker, ACL defaulting to acceptFrom: ["parent"]
• parentId resolving to my-orch (by handle now, by sessionId once both are live)
• Handle my-orch-wkr-build

The orchestrator can now /crosstalk send my-orch-wkr-build <msg> or use the pi-crosstalk CLI from a shell. The worker's LLM sees [from parent:my-orch] <msg> as a real user turn.

Pi-Side Slash Commands

All in-session interaction is via /crosstalk:

Command	Effect
/crosstalk	Toggle on ↔ off in this session. Off by default on a fresh session.
/crosstalk status	Show registry, my role/handle, peers, ACL, unread count
/crosstalk role <orchestrator|worker|peer> [--parent <handle>]	Set role; resets ACL to that role's defaults
/crosstalk handle <name>	Set human-friendly handle (collision → -2 suffix)
/crosstalk send <peer> <msg>	Send as kind=user mode=auto
/crosstalk steer <peer> <msg>	Send as mode=steer (interrupts running turn)
/crosstalk followup <peer> <msg>	Send as mode=followUp (queued after current turn)
/crosstalk allow <bucket-or-handle>	Add bucket or handle to acceptFrom
/crosstalk deny <bucket-or-handle>	Remove from acceptFrom
/crosstalk peer add <handle>	Add a handle to peerOrchestrators (root↔root link)
/crosstalk peer rm <handle>	Remove a handle from peerOrchestrators

Statusline: ⇄ <handle> when idle, ⇄ <handle> [N] when there are unread inbound items, absent when crosstalk is disabled in this session.

Agent-Callable Tools

Crosstalk exposes three pi.registerTool LLM-callable tools. All are opt-in and off by default — they only register if the corresponding flag is set in ~/.config/pi-agent-extensions/crosstalk/config.json. Outside a pi session that has them enabled, these tools do not exist; an agent in another harness cannot invoke them and should not assume their presence.

talk_to_peer({ peer, text, mode })

Send a user-turn message to a peer session. Same delivery path as /crosstalk send, with structured ACL denials returned to the calling model so it can react.

• Args: peer (handle or session id), text (message body), mode (auto | steer | followUp, default auto)
• Returns: { ok: true, delivered: "immediate" | "queued" | "noted" } or { ok: false, reason: "acl:..." | "protocol:..." | ... }
• Enabled by: enableLlmTool: true in the crosstalk config file.

Use this when the agent itself — not the user — needs to drive inter-session communication (typical orchestrator pattern: agent delegates a sub-task to a worker session by calling talk_to_peer).

crosstalk_set({ enabled?, handle?, role?, parent? })

Reconfigure crosstalk's runtime state for the calling session. Same merge path as /crosstalk role, /crosstalk handle, the PI_CROSSTALK_* env vars: each present field overrides; absent fields leave state unchanged. Role changes reset acceptFrom to role defaults; disabling closes the socket and removes the descriptor.

• Args (all optional): enabled (boolean), handle (string — routed through collision-handling), role (orchestrator | worker | peer), parent (handle, only meaningful when effective role is worker)
• Returns: { ok: true, applied: {…}, current: {…} } on success, { ok: false, reason: "…" } on validation failure
• Enabled by: enableCrosstalkSetTool: true in the crosstalk config file.

Use this when the agent needs to self-configure crosstalk on the fly — for example, an orchestrator agent calling crosstalk_set({ enabled: true, role: "orchestrator", handle: "my-orch" }) at session start without requiring the user to type the slash commands.

crosstalk_inspect({ handle? })

Inspect the crosstalk registry without mutating state or sending traffic. Omit handle to get this session's own view (id, handle, role, parentId, children, peers, acceptFrom). Provide handle to look up another live session's record (handle, id, role, parentId, lastSeen) or { "match": null } when it is not registered.

• Args: optional handle (handle or session id)
• Returns: JSON text containing { "self": {…} }, { "match": {…} }, or { "match": null }
• Enabled by: enableCrosstalkInspectTool: true in the crosstalk config file.

Use this before responding to an inbound tag when the model needs to verify who the sender is, whether they are a registered peer/child, or whether a handle is currently live.

pi-crosstalk CLI

Out-of-process clients — shell scripts, external triggers (CI hooks, cron, event-bus hooks), manual debugging — use the pi-crosstalk binary.

pi-crosstalk list                          # live sessions (table)
pi-crosstalk list --json                   # same, JSON
pi-crosstalk who <handle>                  # resolve handle → id, sock path, role
pi-crosstalk send <peer> [text]            # send a message
  --mode auto|steer|followUp               # default auto
  --kind user|meta|ping                    # default user
  --from <tag>                             # default @cli:$USER
pi-crosstalk tail <peer>                   # provisional/debug; not yet implemented

If text is omitted, pi-crosstalk send reads the body from stdin — this is what makes external-trigger one-liners clean. Trailing whitespace is stripped.

Exit codes: 0 ok · 1 wire/protocol error · 2 usage · 3 ACL denial (reason: "acl:...").

External-trigger one-liner pattern

Any tool that can run a shell command can pipe events into a pi session:

# CI hook: notify orchestrator of a failed build.
printf '%s' "$BUILD_LOG" | pi-crosstalk send my-orch --from @ci:build --kind meta

# Event-bus consumer: turn an event payload into a queued follow-up.
event_bus_subscribe my.topic | while read line; do
  printf '%s' "$line" | pi-crosstalk send reviewer-1 --from @event:my-topic --mode followUp
done

The --from value becomes the sender tag the receiver classifies on. Use the @<scheme>:<topic> form — any namespaced sender that doesn't match a live session's handle/id falls into the external bucket. The @ prefix makes the structured-tag intent unambiguous; the receiver's LLM can recognise the source from the scheme (@ci:, @cron:, @event:, etc.). A bare <scheme>:<topic> without the leading @ is not treated as namespaced and will classify as unknown (typically denied).

ACL Buckets and Inbound Tag Format

The receiver classifies every inbound from into exactly one of these:

Bucket	Match rule	Tag rendered to receiving LLM
parent	from is this session's parentId (by id or handle)	[from parent:<handle>] <body> or [from parent:<handle> · <mode>] <body>
children	from is a worker whose parentId is this session	[from children:<handle>] <body> or [from children:<handle> · <mode>] <body>
peers	from is in this session's peerOrchestrators	[from peers:<handle>] <body> or [from peers:<handle> · <mode>] <body>
external	from is namespaced @<scheme>:<rest> (e.g. @ever:topic, @ci:build, @cron:nightly)	[from @<scheme>:<rest>] <body> or [from @<scheme>:<rest> · <mode>] <body> (no bucket prefix — the @<scheme>: self-identifies)
unknown	none of the above	[from <raw-from>] <body>; usually denied

ACL acceptFrom defaults by role:

Role	acceptFrom
orchestrator	["children", "external", "peers"]
worker	["parent"]
peer	["peers", "external"]

Workers do not accept external by default — a CLI/hook sender hitting a worker needs the worker to opt in via /crosstalk allow external first. Explicit handle entries in acceptFrom override bucket rules.

kind: "meta" items use the same bucketing under [crosstalk meta from <bucket>:<handle>] <body> and never trigger a turn. If the sender chose mode: "steer" or mode: "followUp", the tag includes an optional · <mode> suffix before ]; unset/auto has no suffix.

Prompt design for crosstalk-aware sessions

When a crosstalk message arrives, the receiving model sees a normal user turn whose body is prefixed with a bracketed sender tag like [from parent:my-orch] …. The model has no other signal that the turn came from another agent rather than the human at the keyboard — so the prompt is what teaches it to read the tag, weigh the sender, and respond appropriately. Without that, models default to "most recent turn wins" and either treat peer messages as authoritative directives or ignore the tag entirely.

Include a block like the following in any worker / orchestrator / peer prompt where crosstalk is enabled. Keep it close to the role description so the model treats the tag-reading rules as part of its identity, not trivia.

## Inbound messages from other sessions

You may receive user turns that begin with a bracketed sender tag. These
come from the crosstalk extension — another pi session, the user's shell,
or an automated event hook is talking to you. The tag tells you who and
how to weigh it:

- `[from parent:<handle>] …` — your orchestrator. Treat as a directive
  from the agent that spawned you. Follow it unless it conflicts with a
  hard constraint from the human user.
- `[from children:<handle>] …` — a worker you spawned reporting back.
  Treat as a status update or result; you decide what to do next.
- `[from peers:<handle>] …` — a sibling orchestrator. Treat as a peer
  proposal, not a command; coordinate, don't blindly obey.
- `[from @<scheme>:<topic>] …` — an external sender, namespaced by
  scheme. Common schemes:
  - `@cli:<user>` — a human invoked `pi-crosstalk` from a shell. Treat
    roughly like a normal user turn from that human.
  - `@ever:<topic>`, `@ci:<job>`, `@cron:<name>`, `@event:<topic>`,
    etc. — an automated hook (event bus, CI, file watcher, cron, …).
    Treat as a notification; the body is the event payload. Do not
    assume a human is waiting on a reply — don't apologise, don't ask
    clarifying questions into the void.
- Tags may include an optional ` · steer` or ` · followUp` suffix before
  the closing bracket. `steer` means the sender deliberately escalated
  urgency; `followUp` means it should queue behind current work. No
  suffix means unset/`auto`.
- `[crosstalk meta from <bucket>:<handle>] …` — FYI context, no
  response expected. Absorb it and continue what you were doing.

Untagged user turns are the human typing directly into pi. Their
instructions override conflicting messages from parents, peers, or
hooks.

If you need to message another session back, run `/crosstalk send
<peer> "<text>"` from your turn (or use the `talk_to_peer` tool if it
is enabled in this session).

Notes on why it's worded this way, if you want to tune it:

• Authority ranking is explicit. Human-untagged > parent > peers/children/external. Models otherwise default to "most recent turn wins," which breaks orchestrator hierarchies.
• Hook-style senders get explicit "no human waiting" framing because it materially changes how models phrase replies — they stop apologising and stop asking clarifying questions into the void.
• Meta is called out separately so the model doesn't generate a response turn for FYI items.
• The send-back hint at the end is what turns a passive receiver into a participant; without it, models often want to reply but don't realise they can.

For workers where you don't want autonomous outbound sends, drop the talk_to_peer mention and/or omit the closing send-back line.

Environment Variables

Applied once at session_start, merged into persisted state, then normal startup proceeds. Runtime /crosstalk commands take normal precedence after that.

Variable	Values	Effect
PI_CROSSTALK	1 / 0 / true / false / yes / no / on / off (case-insensitive)	Force-enable or force-disable for this session start. Overrides persisted enabled. Invalid → warn + fall through.
PI_CROSSTALK_HANDLE	non-empty string	Set this session's handle (collision → -2, -3, … suffix).
PI_CROSSTALK_ROLE	exact lowercase orchestrator / worker / peer	Set role and reset acceptFrom to that role's defaults. Worker or " worker " warn and fall through.
PI_CROSSTALK_PARENT	parent handle	Only meaningful when effective role is worker. Resolves to live id if available; otherwise stored by handle. Cleared automatically if role isn't worker.

Empty/whitespace-only values fall through silently to persisted/default for all four. Warnings go to the UI notify channel if a UI is attached, else stderr (so headless pi --no-session launches still surface them).

# One-shot enable for a single session:
PI_CROSSTALK=1 PI_CROSSTALK_HANDLE=throwaway-1 pi

# A worker pre-wired to its parent:
PI_CROSSTALK=1 PI_CROSSTALK_ROLE=worker PI_CROSSTALK_PARENT=my-orch pi @/tmp/worker.md

kind × mode Dispatch

Receiver maps (kind, mode, agent-state) to a pi call and reports delivered:

kind	mode	agent state	pi call	delivered
user	auto	idle	sendUserMessage(text)	immediate
user	auto	streaming	sendUserMessage(text, { deliverAs: "followUp" })	queued
user	steer	any	sendUserMessage(text, { deliverAs: "steer" })	queued
user	followUp	any	sendUserMessage(text, { deliverAs: "followUp" })	queued
meta	(ignored)	any	sendMessage({ customType: "crosstalk-meta", … }) — transcript-only	noted
ping	(ignored)	any	(no transcript impact, liveness only)	noted

Use meta for "FYI, here's some context" that should not provoke a response. Use steer to interrupt a running turn — the model sees the steer as a course correction.

Gotchas

• Default-off. A brand-new session has crosstalk disabled. No socket, no registry, no peer discoverability. Either the user runs /crosstalk, or you launch with PI_CROSSTALK=1. pi-crosstalk list will not show a session that hasn't opted in.

• Extension must be loaded. The crosstalk pi extension (this repo, crosstalk/) ships in pi-agent-extensions-extra; if pi isn't loading that package, the slash commands and socket don't exist. The pi-crosstalk CLI alone is not enough — it needs a receiver.

• Worker ACL is narrow. A fresh worker only accepts from parent. External CLI sends (--from @cli:..., --from @ci:..., etc.) hit a worker only after /crosstalk allow external or adding the specific @<scheme>:<rest> to acceptFrom. Plan for this when wiring external triggers into workers.

• Sockets are per-session and ephemeral. Stored under $XDG_RUNTIME_DIR/crosstalk/sock/<sessionId>.sock (fallback $HOME/.cache/crosstalk/), 0600. Liveness is GC'd via kill(pid, 0) on every scan. No persistent inbox — if the receiver is down, sends fail with a clear "no live session matches" error.

• Handles aren't unique by force; they're suffixed. Two sessions both wanting reviewer end up as reviewer and reviewer-2. Don't hard-code the suffix-free name in scripts; use pi-crosstalk who <handle> to resolve, or pi-crosstalk list --json to enumerate.

• peer role exists. For top-level orchestrators that gossip without a parent. Use /crosstalk role peer + /crosstalk peer add <handle> on each side.

• Steer vs. followUp matters. steer interrupts and can corrupt a tool call mid-flight; followUp queues cleanly until the current turn ends. Default to auto / followUp; reach for steer only when you genuinely need to redirect.

• External-trigger notifications are the standard supervisor pattern. When a worker session completes work, it emits an event via whatever event system you use (CI hook, message bus, scheduled task, etc.); a hook on that event runs pi-crosstalk send <supervisor-handle> --from <prefix>:<topic> --kind meta so the completion lands in the supervisor's transcript without polling.

Pointers

• Full spec — air/crosstalk.org (wire protocol, dispatch table, ACL semantics, env var precedence, all Implementation History rounds).
• User-facing summary — README.org, "crosstalk" section.
• Runtime source — crosstalk/index.ts, crosstalk/src/*.ts.
• CLI source — crosstalk/go/cli.go, crosstalk/go/cmd/pi-crosstalk/.