Pi Extension Workflow

Provides: A routing map to the authoritative Pi docs, architecture preferences for composable extensions, a package layout, and a safety checklist.

Quick Reference

Golden Rule: Read the bundled Pi docs before implementing; do not invent API shapes

Flow: Identify type → Read docs and closest example → Check for reuse → Design contracts → Implement → Test with pi -e → Verify /reload

One owner per shared capability. Notifications, status widgets, path protection, configuration, and persistence should each live in exactly one extension.

Required References

This skill deliberately does not duplicate the Pi API. Read the relevant docs from the installed Pi package:

• Always read docs/extensions.md.
• Read docs/tui.md for custom UI, widgets, overlays, renderers, footers, or editor components.
• Read docs/packages.md for package manifests, dependencies, distribution, or install and update behavior.
• Read docs/custom-provider.md for model providers, OAuth, or custom streaming.
• Read docs/keybindings.md for shortcuts or editor key handling.
• Inspect the closest file under examples/extensions/.

Prefer an official example over an invented pattern. The extension API surface changes between Pi versions, so a remembered signature is less reliable than the installed docs.

Design Preferences

• Prefer composable, reusable extensions over one-off monoliths.
• Prefer an extension directory with package.json over a loose .ts file once the extension has dependencies, helpers, tests, reusable contracts, or is expected to persist.
• Keep extension dependencies self-contained in the extension package. Do not add extension-specific dependencies to the global Pi package unless there is no alternative.
• Factor shared behavior into reusable modules or explicit pi.events contracts.
• Prefer optional integration through pi.events, and direct imports only for hard dependencies. Events let an extension work when its counterpart is absent; an import does not.
• Namespace shared event names, for example notifications:show.
• Export constants and TypeScript types for shared event payloads so consumers do not hardcode strings.
• Keep event payloads JSON-serializable unless there is a specific reason not to.

Preferred Layout

For anything beyond a tiny experiment:

my-extension/
├── package.json
├── index.ts
├── src/
│   ├── events.ts
│   ├── state.ts
│   └── tools.ts
└── test/
    └── smoke.test.ts

Minimal local package.json:

{
  "name": "my-pi-extension",
  "private": true,
  "type": "module",
  "dependencies": {},
  "peerDependencies": {
    "@earendil-works/pi-ai": "*",
    "@earendil-works/pi-coding-agent": "*",
    "@earendil-works/pi-tui": "*",
    "typebox": "*"
  },
  "pi": {
    "extensions": ["./index.ts"]
  }
}

Add "keywords": ["pi-package"] only when publishing or distributing.

Workflow

1. Identify the extension type: tool, command, event hook, shared service, UI, provider, or package.
2. Read the matching Pi docs and the closest official example.
3. Check whether an existing extension can be reused or extended instead.
4. Design shared capabilities as modules or documented pi.events contracts.
5. Implement using Pi's documented APIs and TypeScript types.
6. Test with pi -e ./path.
7. If the extension should persist, place it under ~/.pi/agent/extensions/ or .pi/extensions/.
8. Verify /reload works from that auto-discovered location.

Safety Checklist

• Do not hardcode credentials or log secrets.
• Validate paths and user input.
• Avoid shell interpolation. Use pi.exec(command, args) so arguments are passed without a shell.
• Check ctx.hasUI before requiring interactive UI, so the extension still works headless.
• Use abort signals for long-running work where available.
• Bound custom tool output. Unbounded output floods the agent's context.
• Use StringEnum from @earendil-works/pi-ai for tool string enums.
• Throw from a tool's execute() to signal failure; do not return an error string.
• Use withFileMutationQueue() for file-mutating tools so concurrent writes serialize.
• Restore state on session_start.
• Clean up watchers, intervals, sockets, and child processes on session_shutdown.
• Treat ctx.reload() as terminal: await ctx.reload(); return;.

Checklist

Before finishing:

• The relevant Pi docs were read for this extension type
• The closest official example was inspected
• Existing extensions were checked for reuse opportunities
• Shared behavior is a reusable module or a documented event contract
• Shared event names are namespaced, with exported types for payloads
• Dependencies are local to the extension package
• The extension loads with pi -e
• /reload works from an auto-discovered location
• Watchers, intervals, and child processes are cleaned up on shutdown

See also

• Load standards-typescript when writing the extension implementation.
• Load standards-testing for the extension's test coverage.
• Load standards-security when the extension handles credentials, paths, or user input.