monotonic-pi-extensions/working-with-extensions.md

Working with Pi Extensions

Installation Options

Option 1: Publish to npm + pi install (Recommended)

The cleanest path that replicates the official pi experience.

You (publishing):

cd packages/pi-turn-limit
npm publish

Users (installing globally):

pi install npm:pi-turn-limit

This writes to ~/.pi/agent/settings.json under packages. Pi handles the install, runs npm install, and auto-discovers the extension from the pi.extensions manifest.

Option 2: npm global install + settings.json

You (publishing):

npm publish

Users: Two steps — install the npm package globally, then tell pi about it:

npm install -g pi-turn-limit

Then in ~/.pi/agent/settings.json:

{
  "packages": [
    "npm:pi-turn-limit"
  ]
}

Or use the same command as Option 1 — pi install npm:pi-turn-limit does both steps.

Option 3: Local directory (for development)

For local testing without publishing:

pi install /Users/willem/dev/spikes/llm/monotonic-pi-extensions/packages/pi-turn-limit

Or in ~/.pi/agent/settings.json:

{
  "packages": [
    "/Users/willem/dev/spikes/llm/monotonic-pi-extensions/packages/pi-turn-limit"
  ]
}

Or as a single-file extension in ~/.pi/agent/extensions/:

cp packages/pi-turn-limit/src/turn-limit.ts ~/.pi/agent/extensions/turn-limit.ts

Option 4: Per-repo project-local install

Users can install an extension only for a specific project:

pi install -l npm:pi-turn-limit    # -l = project-local

This writes to .pi/settings.json in the project root. Pi auto-installs missing packages on startup per-project.

---

Disabling Extensions Per-Repo

Three approaches:

A. pi config (simplest)

pi config turn-limit:off    # Disable by extension name
pi config turn-limit:on     # Re-enable

Works for both global and project scope. Per-repo:

pi config -l turn-limit:off

B. Package filtering in project settings.json

In .pi/settings.json (project-local):

{
  "packages": [
    {
      "source": "npm:pi-turn-limit",
      "extensions": []    // Load none
    }
  ]
}

Or filter specific files:

{
  "packages": [
    {
      "source": "npm:pi-turn-limit",
      "extensions": ["!src/turn-limit.ts"]  // Exclude this one
    }
  ]
}

C. Remove from settings entirely

pi remove npm:pi-turn-limit

Or manually edit ~/.pi/agent/settings.json and remove the package entry.

---

Summary Table

Method	Scope	User Command
pi install npm:pkg	Global	One command, handles everything
npm i -g + settings.json	Global	Two steps
pi install ./path	Global (symlink-style)	Local dev
pi install -l npm:pkg	Project-local	Per-repo
pi config name:off	Toggle	Enable/disable without uninstalling
pi config -l name:off	Project-local toggle	Per-repo disable

Recommendation: Publish to npm, then users run pi install npm:pi-turn-limit. For disabling per-repo, pi config -l turn-limit:off is the simplest approach — a one-liner that doesn't require editing JSON files.