pi-subagents
One Pi extension for delegation and local agent communication. Three tools, one agent type, no profile bodies.
pi install npm:@fitchmultz/pi-subagents
A main session supplies the child's complete assignment:
delegate({
prompt:
"Inspect the authentication changes. Return concrete defects with file and line evidence. Do not edit files.",
name: "auth-review",
thinking: "low",
});
Delegation is always asynchronous: tools return a receipt and the completion
arrives later as a notification. Do other work or end the turn; do not poll.
context: "fresh" is the default; context: "fork" preserves the native
conversation, including prior tool results. There is no hidden role prompt,
report-writing suffix, profile selection, or model fallback catalog.
Optional thinking sets the child's effort without changing the parent. Omit it
to inherit parent effort. Pi clamps the request to the child's model capabilities.
Guidance and saved continuations keep the child's saved effort.
agent_runs({ action: "list" });
agent_runs({ action: "inspect", id: "<run-id>" });
agent_runs({
action: "continue",
id: "<run-id>",
prompt: "Now inspect the refresh-token path. Do not edit.",
});
agent_runs({ action: "stop", id: "<run-id>" });
Talk to agents
intercom({ action: "list" });
intercom({ action: "send", to: "auth-review", message: "Focus on token rotation." });
intercom({ action: "last", to: "auth-review" });
send steers by default. last reads the peer's last completed assistant response
without waking it; large responses are paged, not silently truncated. Discovery
works across project directories and Pi agent directories under the same OS user.
A main and its children form one group:
- Every pair within that group can discover and communicate with each other.
- Main sessions can discover, message, and read other mains.
- Children cannot discover or address another group's agents—even by exact ID.
- Only mains can delegate. There is one child level, not recursive spawning.
These are coordination rules, not an OS sandbox against same-user code. A peer list contains connected, eligible sessions, not every Pi process on the machine.
Non-model Node.js companions can import
@fitchmultz/pi-subagents/intercom-client for discovery, exact guarded sends,
pinned last-response pages and original-message receipts. The
supported client API connects only
to an existing broker; it loads no Pi SDK, model, TUI or conversation journal.
Bundled skills
The package ships two skills that match tool availability.
pi-subagents covers delegate and agent_runs,
which only main sessions receive. pi-intercom
covers intercom, which every session has, including children and mains that
never delegate. Load either with /skill:pi-subagents or /skill:pi-intercom.
Watch agents without prompting them
In interactive Pi, an above-editor widget names individual children with circle
indicators. The widget lists active work (and unreadable runs) only and disappears
once a full scan finds none. The /agents picker hides completed runs; failed,
stopped, interrupted, and unavailable runs remain visible there.
Click a named row in fullscreen mode to watch it; /agents remains the keyboard
path. Long result/message cards are collapsed and use Pi's native expansion
(Ctrl+O by default). Ctrl+O also expands model/cwd details. Use /agents <run-id> to watch
any saved run, including a completed child's native published text, tool calls and results.
This is read-only: it neither spends a model turn nor dispatches, steers or stops
work. Unpublished provider token deltas are not a journal stream. Agents still
own delegation and communication; human observation is not a second workflow UI.
What stays explicit
Completions steer an active parent at the next tool boundary. An idle completion backlog is published in order and starts one parent turn, not one turn per result.
Launch acceptance is not completion. Broker acceptance is not recipient journal persistence or a reply. A stop request is not proof of process exit. Saved run inspection reports these states separately, and does not invent a successful result when a process disappears.
Children use native Pi sessions and the selected host's SDK, resources, tools,
project instructions, and model configuration. Optional cwd and model
overrides belong to a launch; ordinary continuation reuses its saved conversation
and launch configuration. No user agent Markdown files are edited or consulted
as profiles. On a fitchmultz/pi fork with the toolExposure setting,
subagents.toolExposure keeps tools
that children rarely need out of their requests.
Migration and documentation
This rebuild deliberately removes the profile editor, workflow/chain/fanout DSL,
Claude Code backend, custom agent overlays, supervisor-question revival protocol,
and remote launch/control/catalog APIs. Grok bots retain messaging but lose remote
spawn/resume/session/transcript/group/broadcast access; those retired commands are
not bridge-outage symptoms. Update saved bot prompts/routines to correlated
send before cutover.
Existing installations must finish in-flight work and reload every participating Pi session onto the same approved version before resuming remote traffic. Old and new brokers do not forward across namespaces. Keep the prior package and saved state for rollback; qualify the helper and Box client/worker as an immutable pair, with the companion's offline receipt-reconciliation gate. This repository change does not deploy or restart anything.
Upgrades leave the retired SQLite history index in place. The packaged opt-in offline archive command preserves its complete recovery set after owner-enforced quiescence and observable safety checks. It never runs during startup/install, deletes data, or reclaims disk space.
- Tools and lifecycle
- Local messaging and broker migration
- Authenticated remote messaging / Grok companion
- Development and qualification
- Diagnosis, baseline, and measurable rebuild gates
Supports official Pi and the maintained fitchmultz/pi fork at 1.5.2 or later;
the two hosts are qualified separately, including native Android/Termux. Node.js
is required; see development prerequisites. Source
installs on Android also need an Android-native tsgo on PATH; the prebuilt npm
package does not need a compiler. See
native Android/Termux. MIT licensed.