pi-subagents

Pi extension providing the subagent management engine — spawn background pi sessions, track their output, and interact with them via TUI widgets and LLM-callable tools.

What it provides

| Feature | Description | |---------|-------------| | Session widget | Persistent status bar showing running subagent count | | TUI manager | Interactive overlay (ctrl+up) to navigate, scroll output, stop, and steer subagents | | workflow_spawn_subagent | LLM-callable tool to spawn new subagents | | workflow_list_subagents | LLM-callable tool to list all subagents with status/duration/tokens | | workflow_view_subagent | LLM-callable tool to view a specific subagent's full output | | workflow_stop_subagent | LLM-callable tool to stop a running subagent |

Exports (for use by other extensions)

• spawnSubagent(pi, ctx, command, prompt) — spawn a new subagent, returns { id, intercomTarget }
• updateWidget(ctx?) — refresh the status widget
• openManager(pi, ctx) — open the interactive TUI manager
• SubagentRun — TypeScript interface for subagent state

Usage

Install and load as a pi extension. The extension that provides /workflow-* slash commands is pi-subagents-workflow.

Docs

| Directory | Key pages | |-----------|-----------| | docs/ | architecture, API reference, LLM tools |

Developer instructions

Setup

git clone <repo-url> pi-subagents
cd pi-subagents
npm install

There are no runtime JS dependencies beyond the pi peer dependencies (@earendil-works/pi-coding-agent, @earendil-works/pi-tui, typebox). The extension is loaded directly as TypeScript by pi via jiti.

Loading in pi

Place or symlink index.ts into your pi extensions directory, or configure pi to load it:

# Option A: symlink into pi extensions
ln -s $(pwd)/index.ts ~/.pi/extensions/pi-subagents.ts

# Option B: install globally via npm link, then add to pi config
npm link
# Then add "pi-subagents" to your pi extensions config

Testing

Since the extension spawns real pi subprocesses, the most practical way to test is:

1. Load the extension in pi.
2. Use the workflow_spawn_subagent tool with a simple prompt (e.g. "Write hello world to /tmp/test.txt").
3. Press ctrl+up to open the manager and verify the subagent appears, output streams, and completes.
4. Use workflow_list_subagents / workflow_view_subagent from the LLM to verify tool access.

Code style

• TypeScript with strict types throughout.
• pi-tui Container/Text/Spacer components for TUI rendering — no raw ANSI strings.
• Module-scoped state (runs Map, widgetTui, managerOpen) since pi extensions are singletons.
• All formatting goes through theme tokens (theme.fg(), theme.bg(), theme.bold()).

Architecture

See docs/architecture.md for a detailed walkthrough of the subagent lifecycle, streaming output parsing, TUI component tree, and inter-extension API.

Publishing to npm

Prerequisites

• An npmjs.com account
• The npm CLI logged in: npm login

Build & publish

This extension is distributed as TypeScript source (loaded by pi via jiti), so there is no build step.

# 1. Bump version
npm version patch   # or minor | major | prerelease --preid=beta

# 2. Verify package contents
npm pack --dry-run

# 3. Publish
npm publish

Pre-release checklist

• [ ] package.json version is bumped
• [ ] peerDependencies are correct
• [ ] files field includes index.ts, LICENSE, README.md
• [ ] CHANGELOG or git tag documents the release
• [ ] Tested by loading as a pi extension against the target pi version

After publishing

# Tag the release
git tag v$(node -p "require('./package.json').version")
git push --tags

License

GPL-3.0-or-later — see LICENSE