Pi Extensions AI Agent

🧩 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

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

⭐ Extensions I use every day

These extensions are part of my daily Pi setup:

Extension	Why I use it
pi-btw	Ask a quick side question without polluting the main context.
pi-accounts	Switch between named subscription OAuth accounts.
pi-caffeinate	Keep my machine awake so Pi can keep working.
pi-codex-compact	Spend a little more for better compaction quality.
pi-stamp	See useful details for each response, such as its timestamp.
pi-starship	Match Pi's footer to my Starship shell setup.
pi-sync	Sync my Pi configuration across all my devices through S3.
pi-usage	Check my Codex usage and limit reset times without opening Codex.

📦 Choose an extension

Coding and delegation

Package	Use it for	Install
pi-codex-compact	Use OpenAI Codex Remote Compaction V2 to persist and replay bounded opaque checkpoints, with /codex-compact manual controls and safe Pi-native fallback.	pi install npm:@narumitw/pi-codex-compact
pi-codex-imagegen	Generate images through /codex-imagegen and a default-enabled Codex tool, without starting a Codex agent.	pi install npm:@narumitw/pi-codex-imagegen
pi-context-management	Opt into experimental summary-free context rollover with bounded branch-history recall and branch-local notes.	pi install npm:@narumitw/pi-context-management
pi-files	Browse and attach exact file snapshots, and independently restrict native edits to selected targets through /files.	Build and install locally; not yet published
pi-illustrate	Preview static SVG and Mermaid diagrams through Kitty graphics, with appearance-aware resizing and optional model images.	Install locally; not yet published
pi-lsp	Language-server diagnostics and code actions across JavaScript, TypeScript, Python, Rust, Go, Ruby, C/C++, JVM, .NET, Swift, shell, infrastructure formats, and more.	pi install npm:@narumitw/pi-lsp
pi-plan-mode	Codex-like, read-only /plan collaboration before implementation begins.	pi install npm:@narumitw/pi-plan-mode
pi-subagents	Start bounded background Pi jobs with authenticated main-agent messaging.	pi install npm:@narumitw/pi-subagents

Browser and research

Package	Use it for	Install
pi-chrome-devtools	Inspect tabs, navigate pages, evaluate JavaScript, and capture screenshots through Chrome DevTools Protocol.	pi install npm:@narumitw/pi-chrome-devtools
pi-firecrawl	Scrape pages, crawl websites, discover URLs, and search the web with Firecrawl.	pi install npm:@narumitw/pi-firecrawl

Task and workspace workflows

Package	Use it for	Install
pi-btw	Ask a quick /btw side question without adding it to the main conversation.	pi install npm:@narumitw/pi-btw
pi-caffeinate	Prevent system sleep while Pi processes a long-running prompt.	pi install npm:@narumitw/pi-caffeinate
pi-goal	Keep the agent working until a goal is verified complete; optionally enable an experimental ordered queue.	pi install npm:@narumitw/pi-goal
pi-notes	Browse and edit global Markdown notes in an isolated embedded-agent workspace.	pi install npm:@narumitw/pi-notes
pi-progress	Keep branch-aware multi-step work visible above the editor with the update_progress model tool.	pi install npm:@narumitw/pi-progress
pi-worktree	Create, switch, remove, and prune Git worktrees while carrying the Pi session into another workspace.	pi install npm:@narumitw/pi-worktree

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

Package	Use it for	Install
pi-chat	Join ephemeral peer-to-peer chat rooms that stay separate from Pi sessions, prompts, and model context.	pi install npm:@narumitw/pi-chat
pi-fleet	Start a separate Pi process in a terminal split and connect explicit local Pi sessions for bounded messages and one-turn requests.	pi install npm:@narumitw/pi-fleet
pi-herdr	Report Pi lifecycle state and metadata to Herdr and show sibling agent status.	pi install npm:@narumitw/pi-herdr

Accounts and data

Package	Use it for	Install
pi-accounts	Switch named OpenAI Codex, Anthropic, GitHub Copilot, Kimi For Coding, OpenRouter, Radius, and xAI OAuth accounts with /accounts.	pi install npm:@narumitw/pi-accounts
pi-dotenv	Load one explicit dotenv file early enough for provider credential discovery during normal Pi startup.	pi install npm:@narumitw/pi-dotenv
pi-recall	Save selected text messages locally and preview or quote them across Pi sessions.	pi install npm:@narumitw/pi-recall
pi-usage	View provider usage, limits, reset times, and API balances with /usage.	pi install npm:@narumitw/pi-usage
pi-sync	Sync allowlisted Pi settings and optional sessions through Cloudflare R2 or S3-compatible storage.	pi install npm:@narumitw/pi-sync

Status and observability

Package	Use it for	Install
pi-analytics	Review private, content-free local metrics for model calls, skills, tools, response cycles, and observed provider reliability through /analytics.	pi install npm:@narumitw/pi-analytics
pi-cache-hit-monitor	Show live prompt-cache reuse, token, and estimated cost diagnostics above the editor.	pi install npm:@narumitw/pi-cache-hit-monitor
pi-github-pr	Show current-branch pull request checks, reviews, and comment counts through the authenticated gh CLI.	pi install npm:@narumitw/pi-github-pr
pi-inspect	Inspect current session context and live tool calls in a private, read-only browser viewer with /inspect.	pi install ./packages/pi-inspect
pi-langfuse	Send agent runs, generations, token usage, costs, and tool activity to Langfuse.	pi install npm:@narumitw/pi-langfuse
pi-notify	Send Telegram reminders when Pi settles, with optional inactivity timing and computer/session/worktree details.	pi install ./packages/pi-notify
pi-rex	Show Pi sessions in Rex above the editor and switch to their terminal panes with a click or keyboard picker.	pi install ./packages/pi-rex; not yet published
pi-stamp	Show configurable timestamps with opt-in assistant metadata, response timing, and tool timing in the TUI transcript.	pi install npm:@narumitw/pi-stamp
pi-starship	Use a native Starship-style TOML footer with Pi-specific modules and no Starship binary dependency.	pi install npm:@narumitw/pi-starship
pi-statusline	Show model, tools, Git state, context usage, tokens, cost, and time in a preset or JSON-configured footer.	pi install npm:@narumitw/pi-statusline
pi-tool	Browse every configured tool and inspect its active state, source, parameter schema, and prompt guidelines with /tool.	pi install npm:@narumitw/pi-tool
pi-ticker	Show configurable Yahoo Finance market quotes in a width-aware widget above the editor.	pi install npm:@narumitw/pi-ticker

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

🧱 Extension libraries

Package	Use it for	Install
pi-tui-kit	Extend @earendil-works/pi-tui with reusable navigation helpers and declarative action, detail, settings, and multi-select flows.	npm install @narumitw/pi-tui-kit

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

<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 extension under packages/, so this enables all of them. Its install prepare step generates Kit runtime JavaScript and builds Inspector browser assets before hook setup, even when Pi omits development dependencies.

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

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 builds prerequisites, typechecks the test sources, and runs the root and workspace suites with Vitest. npm run build derives dependency-first order from workspace manifests, builds each prerequisite once, and stops before consumers if a prerequisite fails; workspace-list order is not a build contract. Staged typechecks use the same build planner. 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.

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

npm run package: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 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/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/                Extension packages and reusable libraries
deprecated/              Reference packages excluded from active workspace scripts
docs/                    Repository conventions and plans
.github/scripts/         GitHub Actions versioning and publishing helpers
scripts/                 Shared builds, checks, tests, and local workflow 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/.

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

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

• pi-codex-accounts — replaced by pi-accounts
• pi-file-context and pi-edit-scope — merged into pi-files; follow the migration guide and do not co-load predecessors with the successor
• pi-cbmem — deprecated without a replacement because a simple benchmark found insufficient benefit and substantially higher token 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-image-drop — deprecated without a replacement
• pi-typesafe, pi-typesafe-compact, and pi-typesafe-search — deprecated without a replacement; source retained for reference, with no npm registry deprecation or new release
• pi-workflow — replaced by focused Plan and Goal products; atomic Plan-to-Goal handoff has no replacement
• pi-jupyter — deprecated without a replacement
• pi-webui — deprecated without a replacement
• pi-sidebar
• pi-telegraph
• pi-wait-what

</details>

📄 License

MIT. See LICENSE.