🧩 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

Install the repository as one Pi package:

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

The repository root Pi manifest explicitly lists every stable extension under packages/, so this enables all of them. Packages marked with the experimental lifecycle are intentionally excluded from the root Git package.

To load only selected extensions, replace the installed package entry in ~/.pi/agent/settings.json with a resource filter:

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

Filters use resource paths relative to the repository root. A package directory such as packages/pi-accounts is not enough; select its src/index.ts entrypoint.

Restart Pi or run /reload after changing the filter. Update the checkout later with:

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.

just npm-public @narumitw/pi-new-extension only changes visibility for an existing npm package. If npm returns 404 for a brand-new package, publish it once with public access:

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

After the initial publication, Changesets handles stable extensions, experimental extensions, and libraries through independent package versions.

🦋 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/pi-goal@0.50.0.

Repository-only documentation, tests, tooling, and path migrations may omit a changeset. Use