78 lines
5.8 KiB
Markdown
78 lines
5.8 KiB
Markdown
---
|
|
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.
|