---
status: resolved
parent: "[[002-pi-subagents-map]]"
blocked-by: []
tags:
  - ticket/research
---

# 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.
