Joakim Persson
138 lines
5.6 KiB
Markdown
138 lines
5.6 KiB
Markdown
# pi-extensions
|
|
|
|
Custom and modified extensions for the [pi coding-agent](https://github.com/mariozechner/pi-coding-agent).
|
|
|
|
This repo is the single source of truth for extensions that aren't suitable for general publishing — personal workflow tweaks, modified versions of built-in examples, and extensions written for specific infrastructure. Symlinked into `~/.pi/agent/extensions/` so pi loads them automatically.
|
|
|
|
Part of the same family as [`pi-toolkit`](https://gitea.jordbo.se/joakimp/pi-toolkit) (bring-up) and [`skillset`](https://gitea.jordbo.se/joakimp/skillset) (agent skills).
|
|
|
|
---
|
|
|
|
## Install
|
|
|
|
```bash
|
|
git clone ssh://git@gitea.jordbo.se:2222/joakimp/pi-extensions.git ~/src/src_local/pi-extensions
|
|
cd ~/src/src_local/pi-extensions
|
|
chmod +x install.sh
|
|
./install.sh
|
|
```
|
|
|
|
Each `.ts` file in `extensions/` is symlinked into `~/.pi/agent/extensions/`. Existing real files are backed up with a timestamp. Re-runs are idempotent.
|
|
|
|
**Install a subset:**
|
|
|
|
```bash
|
|
./install.sh --only ssh-controlmaster # just this one
|
|
./install.sh --only "ssh-controlmaster,other" # explicit list
|
|
./install.sh --skip "git-checkpoint" # all except these
|
|
```
|
|
|
|
`--only` and `--skip` accept comma-separated names without the `.ts` suffix. `--only` takes precedence if both are given.
|
|
|
|
### Alternative: pi install (local path)
|
|
|
|
Because `package.json` declares a `pi` manifest, you can also register this repo as a pi package:
|
|
|
|
```bash
|
|
pi install ~/src/src_local/pi-extensions
|
|
```
|
|
|
|
This makes pi manage the extension loading directly. The `install.sh` approach (symlinks) and `pi install` are mutually exclusive for the same extension — pick one per machine.
|
|
|
|
### Uninstall
|
|
|
|
```bash
|
|
./install.sh --uninstall
|
|
```
|
|
|
|
Removes symlinks that point into this repo. Your own files in `~/.pi/agent/extensions/` are never touched.
|
|
|
|
---
|
|
|
|
## Extensions
|
|
|
|
### `ssh-controlmaster.ts`
|
|
|
|
Transparent SSH remote execution via a persistent ControlMaster socket.
|
|
|
|
When launched with `--ssh user@host`, all of pi's native file and shell tools
|
|
(`read`, `write`, `edit`, `bash`) are transparently redirected to execute on
|
|
the remote machine. One SSH connection is established at session start; all
|
|
subsequent tool calls multiplex over it via a Unix socket. Much faster than
|
|
the plain `ssh.ts` example which opens a new connection per tool call.
|
|
|
|
**Use cases:**
|
|
- Diagnose and fix issues on a remote server without installing pi there
|
|
- Work on Proxmox hosts, LXC containers, or ephemeral VMs
|
|
- Any machine you have SSH key access to but don't own
|
|
|
|
**Usage:**
|
|
|
|
```bash
|
|
# Remote home dir resolved automatically via pwd
|
|
pi --ssh user@192.168.1.10
|
|
|
|
# Explicit remote path (skips the initial pwd call)
|
|
pi --ssh root@proxmox-node:/etc/pve
|
|
|
|
# Try without modifying your global install
|
|
pi -e ~/src/src_local/pi-extensions/extensions/ssh-controlmaster.ts --ssh user@host
|
|
```
|
|
|
|
**Requirements:**
|
|
- SSH key-based auth (no password prompts — ControlMaster won't work with interactive auth)
|
|
- `bash` available on the remote
|
|
|
|
**How it works:**
|
|
|
|
1. On `session_start`, runs `ssh -G <host>` to read the effective config for that host
|
|
2. If `~/.ssh/config` already configures `ControlMaster auto` or `yes` for the host, the existing system socket is reused — no second connection is opened and pi does **not** tear down the master on exit (it was the system's to manage)
|
|
3. Otherwise pi establishes its own master: `ssh -fN -o ControlMaster=yes -o ControlPersist=yes -o ControlPath=/tmp/pi-cm-<pid>.sock <remote>` and shuts it down cleanly on exit
|
|
4. All tool calls multiplex over the socket with `-o ControlMaster=no -o ControlPath=<socket>` — near-zero per-call overhead
|
|
5. The system prompt is patched to tell the LLM it's operating on `<remoteCwd> (via SSH ControlMaster: <remote>)`
|
|
6. User `!` shell commands are also routed over SSH
|
|
|
|
The status bar shows `⚡ own master` or `⚡ system master` so you can see which path was taken.
|
|
|
|
**Status bar:** Shows `SSH ⚡ user@host:/path` when the master is ready, `⟳ connecting…` during setup, and an error state if the master fails to start.
|
|
|
|
**Path mapping:** Paths are rewritten by replacing the local `cwd` with the remote `cwd`. This means pi should be started from a directory that maps cleanly to a path on the remote. Use the `user@host:/explicit/path` form when the remote path differs significantly from your local working directory.
|
|
|
|
---
|
|
|
|
## Adding a new extension
|
|
|
|
1. Drop a `.ts` file into `extensions/`
|
|
2. Re-run `./install.sh` — it picks up the new file and symlinks it
|
|
3. In a running pi session, `/reload` is enough; no restart needed
|
|
|
|
Each extension is a TypeScript module loaded by [jiti](https://github.com/unjs/jiti) — no compilation step. See the [pi extensions docs](https://github.com/mariozechner/pi-coding-agent/blob/main/docs/extensions.md) and the [built-in examples](https://github.com/mariozechner/pi-coding-agent/tree/main/examples/extensions) for the API surface.
|
|
|
|
---
|
|
|
|
## Deploying on a new machine
|
|
|
|
```bash
|
|
# 1. Prerequisites: pi installed, SSH key auth working
|
|
pi --help # creates ~/.pi/agent/ on first run
|
|
|
|
# 2. Clone and install
|
|
git clone ssh://git@gitea.jordbo.se:2222/joakimp/pi-extensions.git ~/src/src_local/pi-extensions
|
|
cd ~/src/src_local/pi-extensions && ./install.sh
|
|
|
|
# 3. Verify
|
|
ls -la ~/.pi/agent/extensions/ # should show symlinks into this repo
|
|
```
|
|
|
|
---
|
|
|
|
## Related repos
|
|
|
|
- [`pi-toolkit`](https://gitea.jordbo.se/joakimp/pi-toolkit) — pi bring-up: settings template, keybindings, shell env loader
|
|
- [`mempalace-toolkit`](https://gitea.jordbo.se/joakimp/mempalace-toolkit) — persistent memory layer for pi via MemPalace MCP
|
|
- [`skillset`](https://gitea.jordbo.se/joakimp/skillset) — agent skills for pi, opencode, and Claude
|
|
|
|
## License
|
|
|
|
MIT — see [`LICENSE`](LICENSE).
|