153 lines
3.2 KiB
Markdown
153 lines
3.2 KiB
Markdown
# 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.
|