subagents-pi

Pi extension for subagent fleet metrics — context, TPS, model, and thinking per agent (companion to @tintinweb/pi-subagents)

Packages

Package details

extension

Install subagents-pi from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:subagents-pi
Package
subagents-pi
Version
1.1.0
Published
Sep 28, 2026
Downloads
193/mo · 193/wk
Author
luong.nguyen
License
MIT
Types
extension
Size
80.6 KB
Dependencies
0 dependencies · 2 peers
Pi manifest JSON
{
  "extensions": [
    "./src/index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

subagents-pi

Pi extension that shows a fleet metrics panel for every managed subagent: context usage, output TPS, and thinking level with model name.

Designed as a companion to @tintinweb/pi-subagents, which handles spawning, FleetView, and the Agent tool. This extension listens to the pi.events lifecycle bus and reads the shared agent registry for live stats.

Install

# Orchestration (required for subagents)
pi install npm:@tintinweb/pi-subagents

# Metrics panel (this extension)
pi install npm:subagents-pi

From this monorepo:

./install.sh --auto

Reload Pi: /reload

Usage

  • The panel appears below the editor and lists only active subagents (running / queued). Completed, errored, aborted, and stopped agents leave the list immediately.
  • Layout is an ops-console card: header summary (N active · M queued), glyph status, identity, then width-safe metric lines (context/TPS/duration/tools + thinking/model).
  • /subagents-pi — open a compact enable/disable menu in the TUI (Escape or Close leaves the current state unchanged); outside the TUI it keeps the original toggle behavior
  • /subagents-pi toggle|on|off — toggle or explicitly set the panel without opening a menu
  • /subagents-pi-refresh — refresh metrics and drop finished or removed records (also available from the TUI menu)

Compatibility

The menu is shown only when Pi supplies an extension context with mode === "tui" and hasUI. Older host runtimes that omit ctx.mode use the non-TUI fallback instead of opening UI/RPC dialogs: the bare /subagents-pi command toggles the panel.

Settings persistence

The deliberate /subagents-pi toggle is stored in the private, validated ~/.pi/agent/subagents-pi.json file (the path follows Pi's getAgentDir()). The default remains enabled when no preference is present. Fleet records, metrics, companion readiness, and widget state stay session-only; refreshes and lifecycle events do not write preferences.

What each row shows

Field Source
Status Glyph + compact label (● run, ○ queue)
Context Current context tokens (or — when unavailable) + context-window % (when available) + compaction count
TPS Output tokens ÷ elapsed time (approximate session average); queued agents show waiting
Duration / tools Elapsed time and tool-use count
Thinking/model Runtime session thinking level with runtime provider/model; invocation settings are used as fallback

Acceptance criteria (issue #29)

  • Dedicated installable Pi extension — subagents-pi npm package / extensions/subagents-pi/
  • View listing managed subagents — below-editor widget + status key subagents-pi
  • Per-agent context, TPS, thinking level with model name — rendered on each row

Development

cd extensions/subagents-pi
npm install
npm run build
npm test

License

MIT