Pi extension ecosystem research

Question

What Pi extension APIs, official examples, pi-fork work, and discoverable third-party Pi subagent or popular extensions exist, and do any provide neutral subagent spawning primitives suitable for Herdr-compatible use?

Resolution

Findings

Pi extensions can register tools, commands, shortcuts, flags, event handlers, UI components, message renderers, providers, and resource paths. They are TypeScript modules auto-discovered from ~/.pi/agent/extensions and project-local .pi/extensions, with package distribution through npm or git. Citation: /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/extensions.md.

Pi extension commands have session-control APIs that can create, fork, switch, and message Pi sessions, but the official subagent example instead spawns separate Pi processes. The docs warn that background processes should not be started from the extension factory, and should instead be scoped to session events, commands, tools, or other needful hooks. Citation: Pi docs/extensions.md, especially ExtensionCommandContext, ctx.newSession, ctx.fork, ctx.switchSession, and long-lived resource guidance.

The official Pi examples include examples/extensions/subagent/. It registers a subagent tool, discovers user and project Markdown agent definitions, supports single, parallel, and chained modes, and launches a separate pi --mode json -p --no-session process for each subagent invocation. It also ships sample agents named scout, planner, reviewer, and worker plus workflow prompts. Citation: Pi examples/extensions/subagent/README.md, index.ts, and agents.ts.

The official subagent example is useful mechanism, but it violates the desired policy boundary if adopted as-is because it ships opinionated sample agent definitions and workflow prompts. The core code separates discovery from execution well enough to be mined or adapted, but an adopted extension should not bundle named roles unless those files are excluded from installation. Citation: Pi examples/extensions/subagent/README.md structure and sample-agent table.

A targeted GitHub search found several third-party Pi extensions, including mjakl/pi-subagent, nicobailon/pi-messenger, nicobailon/pi-intercom, owainlewis/pi-extensions, and others. mjakl/pi-subagent is the closest off-the-shelf subagent extension: it supports Markdown-defined agents, fresh or persistent child sessions, parallel calls, parent-context seeding, depth/cycle guards, streaming updates, rich rendering, and Pi 0.80.5 or newer. Citation: GitHub search API result for "pi-coding-agent" extension and /tmp/pi-ext-research/pi-subagent/README.md cloned from github.com/mjakl/pi-subagent.

mjakl/pi-subagent is not purely neutral as packaged. Its README says that if no agents exist, it creates a starter explore agent automatically, and it documents example explore and review definitions. It is closer to the desired boundary than extensions that ship full crews, but automatic starter creation is still opinionated configuration unless it can be disabled or patched. Citation: /tmp/pi-ext-research/pi-subagent/README.md.

mjakl/pi-subagent spawns separate Pi child processes in headless RPC mode, sets PI_OFFLINE=1, and inherits relevant parent CLI configuration. That design is good for frequent context-isolation and latency, but the README does not claim Herdr integration. Citation: /tmp/pi-ext-research/pi-subagent/README.md, technical reference section.

nicobailon/pi-messenger is a broader multi-agent coordination and crew orchestration extension. It ships crew agents, a crew skill, planner/worker/reviewer flows, team roles, approval gates, shared presence, messaging, file reservations, and project-local crew state. It is therefore too opinionated for the requested subagent primitive, though pieces such as presence and orchestration may be informative. Citation: /tmp/pi-ext-research/pi-messenger/README.md.

nicobailon/pi-intercom is a same-machine session-to-session messaging extension, not a subagent spawner. It can integrate with a subagent extension by giving delegated child agents a contact_supervisor tool when bridge metadata is supplied. It could complement a subagent solution, but it does not satisfy spawning or Herdr visibility by itself. Citation: /tmp/pi-ext-research/pi-intercom/README.md.

owainlewis/pi-extensions contains experimental workflow automation and status-message extensions rather than a neutral subagent primitive. Its context-isolated workflow focuses on compaction, testing, review, and iteration inside a workflow command. Citation: /tmp/pi-ext-research/pi-extensions/README.md.

Implications

No researched off-the-shelf Pi subagent extension clearly satisfies all stated criteria today. The best candidate for adaptation is mjakl/pi-subagent, because it already solves repeated isolated child Pi invocations, persistent child sessions, parallelism, and context control. Its likely gaps are Herdr visibility and automatic starter/opinionated agent behavior.

The official Pi subagent example is a strong reference implementation but not a direct adoption target. It is useful for understanding Pi's supported APIs and minimal spawning mechanics.

A new or adapted extension should keep subagent type definitions out of the extension package, avoid automatic starter-agent creation unless explicitly configured, and add a Herdr-aware spawning mode or bridge.

Limitations

GitHub discovery was targeted rather than exhaustive. The pi-fork term did not resolve to a clearly authoritative source during this pass, so it remains an evidence gap unless a specific repository or package name is provided.

5.8 KiB Raw Blame History