# 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):**

```bash
cd packages/pi-turn-limit
npm publish
```

**Users (installing globally):**

```bash
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):**

```bash
npm publish
```

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

```bash
npm install -g pi-turn-limit
```

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

```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:

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

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

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

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

```bash
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:

```bash
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)

```bash
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:

```bash
pi config -l turn-limit:off
```

### B. Package filtering in project `settings.json`

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

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

Or filter specific files:

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

### C. Remove from settings entirely

```bash
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.