🧩 Pi Extensions for the Pi Coding Agent

Independently installable Pi Coding Agent extensions and reusable extension libraries for coding, research, browser automation, workflow management, observability, and terminal ergonomics.

Install only what you need. Every package is published separately under the @narumitw npm scope.

🚀 Quick start

Install an extension permanently:

pi install npm:@narumitw/pi-goal

Try one without adding it permanently:

pi -e npm:@narumitw/pi-statusline

Combine multiple extensions:

pi -e npm:@narumitw/pi-goal \
  -e npm:@narumitw/pi-statusline \
  -e npm:@narumitw/pi-lsp

[!IMPORTANT] Pi extensions run with your full user permissions. Review an extension before installing it from any third party.

📦 Choose an extension

Coding and delegation

Browser and research

Task and workspace workflows

Accounts and data

Status and observability

Choose either pi-starship or pi-statusline; do not enable both footer extensions together.

🧱 Extension libraries

Libraries are runtime dependencies for extension authors, not standalone Pi extensions. New standard manager menus should use @narumitw/pi-tui-kit; extensions continue to own domain state, commands, settings persistence, confirmations, and specialized UI.

🧪 Experimental extensions

[!WARNING] Experimental extensions are published and installable, but their interaction models and package APIs may change between releases.

🔧 Advanced installation

pi install git:github.com/narumiruna/pi-extensions

{
  "packages": [
    {
      "source": "git:github.com/narumiruna/pi-extensions",
      "extensions": [
        "packages/pi-accounts/src/index.ts",
        "packages/pi-usage/src/index.ts"
      ]
    }
  ]
}

pi update --extensions

🧑‍💻 Local development

From the repository root:

npm install
npm test
npm run check

npm test typechecks the test sources and runs the root and workspace suites with Vitest.

Use the generic Just recipes with an unscoped extension name:

just try goal
just pack goal

# Experimental packages use the same recipes
just try file-context
just pack file-context

# Libraries use the same generic pack recipe
just pack tui-kit

Run just --list to see all development, install, pack, and release recipes. Pull requests that change published package behavior should add release intent with npm run changeset; packages version independently.

npm publish --workspace @narumitw/pi-new-extension --access public

🦋 Releases

A behavior-changing package pull request records its affected packages and SemVer bumps with:

npm run changeset

After changesets reach main, the release workflow creates or updates one version pull request. That pull request changes only selected package versions, dependency ranges where configured, changelogs, and the lockfile. Merging it publishes the new versions with npm provenance and creates package-specific tags and GitHub releases such as @narumitw/[email protected].

Repository-only documentation, tests, tooling, and path migrations may omit a changeset. Use npm run changeset:status to inspect pending releases. Versioning and publication run through the release workflow; initial publication remains the manually approved exception described above.

@narumitw/pi-tui-kit remains independently versioned. Publish a new Kit API before raising an extension's compatibility floor to consume it; do not release an unpublished Kit API and its first consumer together.

🗂️ Repository structure

packages/                Stable extensions, experimental extensions, and reusable libraries
deprecated/              Reference packages excluded from active workspace scripts
docs/                    Repository conventions and plans
scripts/                 Shared checks, tests, versioning, and release helpers
test/                    Root integration and repository tests

Each active package contains its own package.json, README.md, LICENSE, tsconfig.json, and TypeScript source under src/. Extension src/index.ts files are thin Pi entrypoints and declare a stable or experimental lifecycle; reusable libraries publish built ESM and declarations from dist/.

📄 License

MIT. See LICENSE.