A monorepo of Pi extensions. Every directory under packages/
is independently publishable to npm and independently understandable; the
private root is never published and declares no Pi manifest.
Two of them are designed as a pair — start there.
pi-subagents runs agents. pi-workflows decides which agents to run and in
what order. Neither reaches into the other: a workflow dispatches through a
typed event-bus protocol, and the subagent runtime stays the only thing that
knows what a model costs.
┌─ pi-workflows ─────────────────┐ ┌─ pi-subagents ─────────────────┐
│ what runs, and in what order │ │ how an agent actually runs │
│ │ spawn- │ │
│ • agent() parallel() pipeline │ managed │ • model + thinking (tiers) │
│ • phases, budgets, checkpoint │ ──────▶ │ • tools, skills, cwd │
│ • journal + resume │ │ • queue, concurrency, retry │
│ • verify / judgePanel / gate │ │ • transcripts, stop, isolation│
└────────────────────────────────┘ └────────────────────────────────┘
└───── @signalridge/pi-subagents-protocol (shared wire contracts) ────┘
Install both — they are separate Pi packages, and the peer dependency documents the requirement without auto-loading the other half:
pi install npm:@signalridge/pi-subagents # >= 1.9.0, protocol v4
pi install npm:@signalridge/pi-workflowsA workflow is a plain JavaScript module. It fans work out; the runtime decides how that fan-out is actually paid for:
export const meta = { name: "audit", description: "Scan, then synthesize" };
const findings = await parallel([
() => agent("Check for cross-package imports", { strength: "low" }),
() => agent("Check for secrets", { strength: "low" }),
]);
return agent("Synthesize: " + JSON.stringify(findings), { strength: "high" });| Question | Answered by |
|---|---|
| What work happens, in what order, with what recovery | pi-workflows — its DAG, its journal, its resume |
| How much a step is worth | the script names a strength (low / medium / high) |
| Which model that strength becomes | pi-subagents — its Agent tier catalogue, its resolver |
| How wide a fan-out really goes | pi-subagents — a run reads maxConcurrent live and is clamped to it |
| Tools, skills, cwd, isolation, transcripts, stop | pi-subagents, for workflow children exactly as for any other agent |
A workflow script is generated by the user's own model. If it could name a
model, a thinking level, or a tool policy, an LLM-authored file would be
choosing what the host pays and what the host exposes. So the script's entire
cost vocabulary is three words, and a strengths table — not the script — binds
each word to a tier the host defined:
/workflows strength edits that table and prints the tiers the host defines —
the one place both halves are visible. There is deliberately no second tier
configuration file, and no per-call model or tier option to reach past it.
The same reasoning shapes concurrency: a workflow does not configure it. A
workflow agent occupies one of pi-subagents' background slots like any other
agent, so a single setting governs the whole fleet.
Full detail lives in each package's README —
pi-workflows for the runtime globals,
resume semantics, and routing table;
pi-subagents for agent types, tiers,
FleetView, and scheduling. The tested development host is Pi 1.0.4.
Host-provided peers use "*" for module ownership, not as a claim that every Pi
version is supported. See compatibility and verification
for current host contracts and integration limits.
Packages are installed individually; each package's own pi.extensions
manifest controls what Pi loads.
pi install npm:@signalridge/pi-subagents
pi install npm:@signalridge/pi-workflows
pi install npm:@signalridge/pi-lsp
pi install npm:@signalridge/pi-ask-user-questionInstall any one package from a single source. An npm copy alongside a local checkout of the same package loads both, and the duplicate registers its tools twice.
To run from this checkout, load the local directories and skip the installed
catalogue with -ne:
pi -ne -e ./packages/pi-subagents -e ./packages/pi-workflows| Package | What it does |
|---|---|
pi-subagents |
Managed subagent runtime — tiers, workflow-owner Fleet groups, queueing, isolation, scheduling, RPC and opt-in background clarification to the main agent |
pi-workflows |
JavaScript orchestration over those subagents — fan-out, phases, budgets, quality helpers, journal-backed resume |
pi-goal |
Autonomous /goal completion, with opt-in experimental ordered queues |
pi-ralph-wiggum |
Long-running agent loops for iterative development |
pi-plan-mode |
Codex-like read-only /plan collaboration mode |
pi-agent-guidance |
Loads provider-specific context files (CLAUDE.md, CODEX.md, GEMINI.md) based on the current model |
pi-ask-user-question |
Structured user-question tool for agents |
| Package | What it does |
|---|---|
pi-lsp |
Language-agnostic LSP tools through a shared runner |
pi-github-pr |
GitHub pull request review, checks, and comment status |
pi-code-actions |
Pick code blocks from recent assistant messages to copy or insert |
pi-files-widget |
In-terminal file browser and viewer |
pi-btw |
/btw side-question command; parent-history sharing is per-question opt-in |
pi-stamp |
Transcript timestamps, assistant metadata, and tool timing |
| Package | What it does |
|---|---|
pi-statusline |
Theme-native statusline |
pi-input-prefix |
Theme-aware rounded input editor and prompt token |
pi-input-history |
Text-preserving prompt history with grapheme-safe search/highlights and an fzf/atuin-style Ctrl+R picker |
pi-welcome |
Startup resource and repository summary card |
pi-session-recap |
While-you-were-away recap above the editor; raw-history requests require explicit model and consent flags |
pi-tab-status |
Terminal tab status indicators |
pi-usage-extension |
Usage statistics dashboard |
| Package | What it does |
|---|---|
pi-gpt-fast |
Opt-in OpenAI and Codex priority service tier |
pi-herdr-state |
Reports Pi lifecycle state to herdr |
Publishable, but install them deliberately rather than as part of a default set.
| Package | What it does | Requires |
|---|---|---|
pi-worktree |
Safe interactive Git worktree management and workspace switching | A project that allows git worktrees |
pi-worktime |
Per-prompt active worktime tracking | — |
Marked piExtension.lifecycle: experimental, which keeps them out of a release
unless a changeset names them: pi-recall, pi-codex-compact, pi-analytics,
pi-background (session-owned background
shell jobs and event-driven log monitors; local macOS/Linux only), and
pi-todo (revisioned, branch-local checklists with
explicit manual controls; not a project backlog or execution scheduler),
pi-approvals (per-operation reviewed local
writes/edits and commands; opt-in adapters, not an OS sandbox), and
pi-sessions (human-owned history navigation
and editable linked-session handoff; destination draft only, never auto-send).
Not Pi extensions. They register no resources, hold no state, and are consumed as ordinary npm dependencies — never listed in Pi's extension package map.
| Package | What it does |
|---|---|
pi-subagents-protocol |
Side-effect-free wire contracts for the managed subagent protocol |
pi-ui |
Side-effect-free bordered UI, inert display encoding and opt-in public custom-editor preservation adapters |
pi-approval-core |
Side-effect-free local approval contracts, cooperative-adapter validation and reviewed native-tool factories; no Pi resources |
Packages communicate through Pi's public APIs and pi.events; no extension
imports another extension's source. Each package owns a defined area — the
footer, the input editor, the workflow journal, the subagent queue — and
consumes other packages' state without mutating it.
docs/package-boundaries.md is the ownership
matrix, including persistence boundaries and the one-declared-range rule for
shared rendering dependencies.
bun install --frozen-lockfile
bun run check # format + lint + typecheck + testEvery package owns its own lint, typecheck, test, format, and check
scripts, runnable individually. Run bun run check before committing.
A change to a published package needs a changeset naming it:
bun run changeset
bun run changeset:statusThe Actions workflow opens a Version Packages PR once changes reach main;
merging it publishes only the changed packages, via npm Trusted
Publishing/OIDC. See docs/releasing.md for setup,
bootstrap, rate-limit, and recovery guidance.
The custom packer and integrity-safe publisher remain available for bootstrap and recovery — not for normal Changesets releases:
bun run release:pack -- --package=pi-lsp
bun run release:publish:recovery -- --package=pi-lsp --dry-run
printf '%s' "$NPM_TOKEN" | bun run release:publish:token -- --token-stdin --package=pi-new-package --tag latestBootstrap and token mode require exactly one selected package. Experimental packages are packed or published only when intentionally selected.
See LEGAL-NOTICES.md for retained license handling, and
AGENTS.md for the repository's authoring rules.
- Package boundaries: runtime ownership, persistence and shared contracts.
- Extension portfolio: each capability's value, alternatives and conditional use.
- Upstream review, 2026-10-23: pinned sources, selective ports and deferred candidates.
- Compatibility and verification: tested host, dependency ownership and integration limits.
- Design decisions: isolation, deferred imports, orchestration and resource admission.
- Task and status navigation: shell-job views, status-owner actions and the UI protocol.
- Release guide: independent versioning, publication and recovery.