pi-extension-starter

pi-extension-starter is a starter kit for developers who want to build extensions for the pi CLI.

If your question is "what does this repository actually do?", the short answer is: it gives you a ready-to-clone, source-first npm package that already behaves like a real pi extension. You replace the sample command, tool, and UI with your own feature instead of wiring the package from zero.

pi already provides the extension APIs. This repository exists to show how to put those APIs together in a practical package structure that is easy to develop, test, and publish.

What This Repository Is

• A starter template for authoring pi extensions
• A working example of recommended pi extension patterns
• A publishable npm package with TypeScript as the extension entrypoint

What This Repository Is Not

• Not a finished end-user extension by itself
• Not a replacement for built-in pi features
• Not a framework on top of pi

The included settings panel and checklist tool are sample features. Their job is to demonstrate the extension APIs in a realistic way. You are expected to rename or replace them in your own package.

What The Starter Includes

• package.json > pi.extensions pointing to ./src/index.ts
• A source-first TypeScript entrypoint with no mandatory build step
• An example slash command: /starter-settings
• An example tool: starter_checklist
• Persisted session settings via pi.appendEntry()
• Branch-aware tool state stored in tool result details
• An interactive SettingsList panel built with ctx.ui.custom()
• Lifecycle hooks for session_start, session_tree, and model_select
• Custom status and footer rendering
• Reusable test helpers in test/helpers/
• Local validation scripts and automated release workflows

What The Sample Extension Does Out Of The Box

• /starter-settings opens an interactive settings panel
• starter_checklist manages a small sample checklist
• The footer and status reflect the current settings and checklist summary
• Model changes can trigger a notification
• State is restored on session reloads and branch changes

Those behaviors are examples, not the point of the project. The point is the starter structure around them.

When To Use This Starter

Use it when you want to:

• Create a new pi extension package quickly
• Follow the current pi patterns instead of inventing your own wiring
• Keep extension state working across reloads, fork, and tree
• Start from a repo that is already set up for tests, packaging, and release

Quick Start

npm install
npm run check
pi -e ./src/index.ts

Then:

1. Update the package metadata in package.json.
2. Rename the public identifiers in src/types.ts.
3. Replace the sample command, tool, and UI with your own extension behavior.
4. Optionally test package installation with pi install ..

Project Layout

src/
  index.ts
  commands/
    settings-command.ts
  state/
    session-state.ts
  tools/
    starter-checklist-tool.ts
  ui/
    footer.ts
    settings-panel.ts
  types.ts
test/
  helpers/
    mock-command-context.ts
    mock-extension-api.ts
    mock-extension-context.ts
    mock-footer-data.ts
  index.test.ts
docs/
  pi-guide-1-base.md
  pi-guide-2-runtime.md
  pi-guide-3-release.md

Key Files

• src/index.ts: registers the command, tool, and lifecycle hooks
• src/commands/settings-command.ts: example interactive command using SettingsList
• src/state/session-state.ts: session persistence and rehydration
• src/tools/starter-checklist-tool.ts: example tool using defineTool() and typed details
• src/ui/footer.ts: status and footer rendering
• src/ui/settings-panel.ts: interactive TUI panel
• test/helpers/: mocks for extension tests

Validation And Release

npm run check runs:

• TypeScript typecheck
• lint
• format check
• tests
• npm pack --dry-run

Before publishing, confirm:

npm run check
npm run pack:check

The repository also includes:

• validate.yml to run validation on pushes and pull requests
• release.yml to manage releases with release-please and publish to npm

Customize Before Publishing

• package.json
  • name
  • description
  • author
  • repository
  • bugs
  • homepage
• src/types.ts
  • command name
  • tool name
  • session entry type
  • default settings
• Sample settings and checklist behavior
• LICENSE

Local Documentation

This starter treats the following files as the local implementation contract:

• AGENTS.md
• docs/pi-guide-1-base.md
• docs/pi-guide-2-runtime.md
• docs/pi-guide-3-release.md

Those guides were derived from the official pi docs and examples in:

• packages/coding-agent/docs/extensions.md
• packages/coding-agent/docs/packages.md
• packages/coding-agent/examples/extensions/README.md

Notes

• The package stays source-first, so pi loads the extension directly from TypeScript.
• Core pi dependencies stay in peerDependencies with "*".
• @mariozechner/pi-ai is included because StringEnum() is part of the recommended enum pattern.