🧩 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

Current Plan and Goal releases can coexist on the characterized Pi runtime through their anonymous cooperative workflow mutex. The deprecated combined pi-workflow package has no atomic Plan-to-Goal replacement; follow its archived migration instructions.

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.

Build generated entries before loading local packages, and use the generic Just pack recipe with an unscoped package name:

npm --workspace @narumitw/pi-goal run build --if-present
pi -e ./packages/pi-goal
just pack goal

# Another build-backed package uses the same local flow and pack recipe
npm --workspace @narumitw/pi-file-context run build --if-present
pi -e ./packages/pi-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/pi-goal@0.50.0.

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/. Every extension keeps a thin src/index.ts source forwarder and declares a stable or experimental lifecycle. An extension package may load that source entrypoint directly or publish a build-backed dist/index.ts bundle for Pi's Jiti runtime. Reusable libraries publish built ESM and declarations from dist/.

📄 License

MIT. See LICENSE.