pi-extensions

🧩 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. Published packages use the @narumitw npm scope, and package READMEs identify source-only exceptions.

🚀 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

⭐ Extensions I use every day

These extensions are part of my daily Pi setup:

📦 Choose an extension

Coding and delegation

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.

Local collaboration

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.

🔧 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

Use Node.js from .node-version with its bundled npm, then run from the repository root:

node scripts/check-install-policy.mjs
npm install
npm test
npm run check

npm test typechecks the test sources and runs the root and workspace suites with Vitest. See test performance and isolation for package timing reports, cache behavior, and the reviewed shared-module test boundary. CI and release use npm ci with strict dependency script review and a three-day minimum age for new resolution. See dependency installation policy for script approvals, lockfile-age limitations, failed-update recovery, urgent-patch review, and toolchain upgrades.

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

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

# Pi Files requires a local build; it is not yet published to npm
npm --workspace @narumitw/pi-files run build --if-present
pi -e ./packages/pi-files
npm run package:pack -- files

# Libraries use the same generic pack workflow
npm run package:pack -- tui-kit

Run npm run to see all development, install, pack, and release workflows. 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/                Extension packages 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 one package entrypoint. 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.