🧩 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.

Browser companions

🧱 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

<details>
<summary>Install this repository directly from GitHub</summary>

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

</details>

🧑‍💻 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.

<details>
<summary>Publishing a new scoped package</summary>

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.

</details>

🦋 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/.

<details>
<summary>Deprecated packages</summary>

The following packages remain available as source references but are excluded from active workspace scripts:

• pi-biome-lsp and pi-python-lsp — replaced by pi-lsp
• pi-codex-accounts — replaced by pi-accounts
• pi-codex-usage — replaced by pi-usage
• pi-retry — replaced by Pi's built-in provider retry and timeout behavior
• pi-google-genai — replaced by the grounding-with-google-genai agent skill
• pi-jupyter — deprecated without a replacement
• pi-auto-thinking
• pi-sidebar
• pi-telegram-bot
• pi-telegraph
• pi-wait-what

</details>

📄 License

MIT. See LICENSE.