@gagansd/pi-subagents

Benchmark

These frozen figures are from a prior measured campaign, not measurements or a rebenchmark of this new release's changed artifact. Both models ran through the same five dynamic workflow tasks using different subagents packages. See the benchmark methodology.

Installation

pi install npm:@gagansd/pi-subagents

Then /reload. Supports stable Pi 1.x (>=1.0.0 <2.0.0), including 1.1.x, using the local npm installation on Node in interactive mode. Prereleases, Bun, and print/RPC/standalone hosts are not supported.

Features

• Delegate bounded work from one agent session to worker and reviewer sub-agents
• Fresh native Pi sessions, session-bound, no nested delegation
• subagent tool: run (1–4 tasks), list, status, resume, steer, stop, reply
• /subagents to attach, resume, steer, reply, or stop
• Focusable worker roster and dedicated conversations; settled runs leave the roster
• Supports Markdown agent profiles
• Local reports and transcripts

Model and thinking selection

Model and thinking resolve from the task, then the profile, then the owning agent. Models can support different thinking levels. If a selected level is unsupported, the batch is rejected before any sub-agent launches and the error lists the valid levels. Set tasks[].thinking or the profile's thinking explicitly; the package never silently falls back to a different model or thinking level.

Human navigation

Rows use stable names such as Worker 1 · Implement the parser · Running. Ordinals distinguish duplicate roles and never renumber when a sibling finishes. Run/session UUIDs and PID are not primary navigation labels.

• Down at the editor boundary focuses the roster, without opening anything (tui.editor.cursorDown, Down by default). Native movement, history, autocomplete and selection run first. If Down still moves your caret or clears a selection, press it again after that movement finishes.
• Up/Down selects, including the configured tui.editor.cursorDown handoff key and tui.select.* bindings; PageUp/PageDown jump a window. Enter/Space opens. Esc, or Up from the first row, returns to the original editor. Typing returns there with that input intact.
• Click selects; double-click opens. /subagents remains the portable entry point.
• In a thread, Space/arrows edit normally. Tab/Shift+Tab moves among message, conversation and actions; PageUp/PageDown scrolls. Esc/Back returns.
• Details exposes technical evidence; Tools expands tool output; Older/Latest pages conversation history. Stop requires confirmation and stays available independently of an in-flight send. Resume appears only for a transient provider failure with a saved transcript and also requires confirmation.

The thread paints the whole conversation workspace, not a translucent diagnostic popup. With cooperative Slate and a compatible fullscreen Pi 1.1+ host, it borrows Slate's chat slot while retaining its sidebar. The sidebar still describes the parent workspace; worker-specific usage/workspace is in Details. Parent dialogs reclaim the workspace without losing focus, and the worker draft is retained.

Without an owned workspace bridge (plain Pi, regular mode or older hosts), an opaque full-viewport conversation is the disclosed fallback; it does not claim sidebar preservation. If an offered workspace becomes unavailable or fails to mount, a warning and thread note disclose the fallback. Other custom editors are not replaced or assigned global Down interception. The original main editor/chat objects survive switching, including native undo/paste/cursor state and background parent output.

Per-run drafts and reading positions survive switching. Send failures keep the text; success clears only the submitted revision. A draft bound to an old question cannot silently answer a replacement question. Completions never jump focus: settled runs leave the roster as soon as they finish, fail, or cancel. Live workers stay in the idle window and page with focused Up/Down navigation. /subagents still opens saved reports. Finished means a saved report, not verified work.

Session dashboards

When a session dashboard such as Slate is installed, sub-agents also publish optional pi:background-tasks display snapshots and answer matching-owner pi:background-tasks:request events. Completed/cancelled runs leave that shelf; live/uncertain-cleanup runs take priority over bounded failed history (64 rows per source). Snapshots include exact run IDs, state and shared host PID, not native session objects, private questions or run control. Use /subagents for authoritative inspection and control. Listener failures cannot change run outcomes; reload/shutdown clears the source.

Telemetry and evidence

Details shows exact run/session IDs, shared process PID, cwd, model/thinking, context estimate, usage and artifact paths. /subagents <run-id-or-prefix> still routes by the manager's run UUID, never a native session ID. Exact machine-facing JSON and saved run.json/reports/transcripts are unchanged.

Sub-agents are in-process native Pi SDK sessions, not separate worker processes. Context occupancy is Pi's estimated current usage divided by the selected context window, not cumulative billed tokens. Unknown remains unknown; real zero and values above 100% are preserved. Estimates refresh at finalized lifecycle/compaction boundaries, never on streamed tokens or paint.

Conversation pages are asynchronous bounded reads of finalized messages. Long entries/older content disclose omission; original transcript/report paths remain available in Details. Rendering does no filesystem reads or model calls.