# AGENTS.md

## What this is

A version-controlled collection of custom and modified pi coding-agent extensions,
symlinked into `~/.pi/agent/extensions/` by `install.sh`.

Companion to [`pi-toolkit`](https://gitea.jordbo.se/joakimp/pi-toolkit) (bring-up,
keybindings, env loader) — that repo gets pi running; this repo adds behaviour on
top of it. Also related to [`skillset`](https://gitea.jordbo.se/joakimp/skillset)
which does the same job for agent skills.

Read [`README.md`](README.md) first for the user-facing walk-through.
This file is for agents modifying the repo.

## Structure

```
extensions/
  ssh-controlmaster.ts    # ControlMaster SSH remote execution (see below)
  confirm-destructive.ts  # Confirm before dangerous bash commands and session actions
  git-checkpoint.ts       # Git stash checkpoint per turn, restorable on /fork
  notify.ts               # Native terminal notification when agent finishes
  ext-toggle.ts           # /ext slash command — list & toggle extensions at runtime
  todo.ts                 # `todo` tool for the agent + /todos for the user (copy of upstream example)
  mcp-loader.ts           # Generic MCP server loader + /mcp slash command
install.sh                # Idempotent installer — symlinks extensions/ into ~/.pi/agent/extensions/
package.json              # pi package manifest — enables `pi install /path` as an alternative
README.md                 # User-facing docs.
AGENTS.md                 # This file.
LICENSE                   # MIT.
```

## Conventions

- **Extension imports are coupled to the running pi version.** Extensions are loaded by jiti at runtime; their `import { ... } from "@earendil-works/pi-*"` statements resolve against whatever node_modules the running `pi` binary has bundled. **When extension imports change package names** (e.g. the 2026-05-09 rename from `@mariozechner/pi-*` to `@earendil-works/pi-*`), the host pi MUST be upgraded to the matching version *before or at the same time as* the import-rename push, otherwise users on the older pi see `Cannot find module '@earendil-works/...'` at extension load. Container path: bump `PI_VERSION` build-arg in opencode-devbox. Host path: `npm install -g @earendil-works/pi-coding-agent` (and `brew uninstall pi-coding-agent` if previously installed via brew at the old name). `bun build --external '*'` does NOT catch this regression — it only validates the bundle shape, not module resolution against the runtime pi's deps. Real test: run `pi --version` on the target system after the rename.

- **One `.ts` file per extension**, flat under `extensions/`. If an extension
  grows multiple files, use a subdirectory with an `index.ts` entry point —
  pi's auto-discovery handles both shapes.
- **Extensions are symlinked, not copied.** `ln -s <repo>/extensions/foo.ts
  ~/.pi/agent/extensions/foo.ts`. Edits flow through git without a re-install
  step. The symlink is what pi loads at startup.
- **Existing files at link destinations are backed up** with a timestamp
  (`.bak.YYYYMMDD-HHMMSS`) before a new symlink is created. Never silently
  overwrite.
- **`install.sh` is idempotent.** Re-running it is always safe. Links already
  pointing into this repo are left alone (`link_into_repo` guard).
- **`--only` / `--skip` flags** for subset installs. `--only` is an explicit
  allowlist; `--skip` starts with everything and removes named entries; `--only`
  wins if both are given. Names are bare (no `.ts`).
- **No always-on side effects at module load time.** Extensions should be inert
  unless the user passes a flag or the relevant event fires. The `--ssh` flag in
  `ssh-controlmaster.ts` is the model: the module loads on every pi session but
  does nothing unless `--ssh` is present.
- **Extension flag names must be globally unique** across all installed extensions.
  Prefix with a short namespace if there's any risk of collision
  (e.g. `ssh-` for ssh-related flags).

## What `install.sh` does

1. `require_pi_installed` — aborts with exit 4 if `~/.pi/agent/` is missing.
   Creates `~/.pi/agent/extensions/` proactively.
2. Calls `build_install_set` to resolve which extensions to install based on
   `--only` / `--skip` flags (default: all `.ts` files in `extensions/`).
3. For each selected extension: symlinks `extensions/<name>.ts` →
   `~/.pi/agent/extensions/<name>.ts`. Backs up any pre-existing real file or
   foreign symlink.

Uninstall: removes symlinks that point into this repo, leaves everything else
untouched.

## Adding a new extension

1. **Drop a `.ts` file into `extensions/`.** No other config needed —
   `install.sh` discovers all `.ts` files automatically.
2. **Export a default factory function** `(pi: ExtensionAPI) => void`.
   See the [pi extensions docs](https://github.com/earendil-works/pi/blob/main/docs/extensions.md)
   and [built-in examples](https://github.com/earendil-works/pi/tree/main/examples/extensions).
3. **Register any CLI flags** via `pi.registerFlag()` so they appear in
   `pi --help`.
4. **Keep the extension inert without its flag** (or equivalent trigger). Don't
   run side effects unconditionally at load time.
5. **Update `README.md`** — add an entry under the Extensions section
   documenting flags, use cases, requirements, and how it works.
6. **Re-run `./install.sh`** — it picks up the new file and symlinks it.
   In a running pi session, `/reload` is enough; no restart needed.

## Extension-specific notes

### `ssh-controlmaster.ts`

Overrides the four native pi tools (`read`, `write`, `edit`, `bash`) to execute
on a remote machine via SSH when `--ssh user@host` is passed.

**Key design decisions:**

- **ControlMaster negotiation via `ssh -G`.**  
  Before starting any connection, `readSshConfig(remote)` runs `ssh -G <host>`
  and inspects the `controlmaster` and `controlpath` fields. If the effective
  config already has `ControlMaster auto` or `yes`, the system socket is reused
  (`ownsmaster: false`). Otherwise, the extension starts its own master at
  `/tmp/pi-cm-<pid>.sock` (`ownsmaster: true`). The `session_shutdown` handler
  only calls `ssh -O exit` when `ownsmaster` is true — it never tears down a
  connection it didn't create.

- **Password auth via `--ssh-ask-pass`.**  
  When the flag is set, `ctx.ui.input()` prompts for a password before
  connecting. The password is passed to SSH via `SSH_ASKPASS`: a temp script at
  `/tmp/pi-askpass-<pid>.sh` (`chmod 700`) is written, SSH is spawned with
  `SSH_ASKPASS` + `SSH_ASKPASS_REQUIRE=force` (plus `DISPLAY=dummy` for older
  OpenSSH), and the script is deleted in a `finally` block. Input is **not**
  masked — visible while typing.

- **Path mapping.**  
  Remote paths are derived by replacing the local `cwd` with `remoteCwd` in
  every path argument. This works cleanly when pi is started from a directory
  that has a matching counterpart on the remote. Use the `user@host:/path` form
  when the paths diverge.

- **`ownsmaster` vs system master and `--ssh-ask-pass`.**  
  If the system already has a ControlMaster configured for the target host,
  `--ssh-ask-pass` is silently ignored — the system master handles auth
  independently and the socket is just reused.

### `confirm-destructive.ts`

Always-on (no flag). Two layers:

1. **Bash gate** — intercepts `tool_call` for `bash` and checks the command
   against a pattern list. On match, shows a `select` dialog. Blocks in
   non-interactive mode by default.
   Patterns: recursive `rm`, `sudo`, `chmod/chown 777`, `dd if=`, `mkfs`,
   `git push --force`, writes to `/dev/*`, `truncate --size 0`.

2. **Session gate** — hooks `session_before_switch` and `session_before_fork`.
   Confirms before `/new` (clear) and `/resume` (switch, only if there are
   unsaved messages). Always confirms before `/fork`.

When adding new patterns, add to the `DANGEROUS` array at the top of the file.
Each entry has a `pattern` (RegExp) and a `label` shown in the dialog.

### `git-checkpoint.ts`

Always-on. Silently skips when the `cwd` is not inside a git repo.

- At `turn_start`: runs `git stash create` (non-destructive — creates a stash
  object without touching the working tree). Stores the stash ref keyed to
  the current session entry ID. Empty output (nothing to stash) is silently
  ignored.
- At `session_before_fork`: if a checkpoint exists for the selected entry,
  offers to `git stash apply` it.
- Status bar shows `⎇ N checkpoints` when checkpoints are present.
- Checkpoints are in-memory only — they do not survive a pi restart, but stash
  objects remain in the git repo and can be applied manually.

### `notify.ts`

Always-on. Records `agent_start` timestamp; on `agent_end` checks if elapsed
time exceeds `--notify-min-secs` (default 8). Silently skips short responses.

Terminal detection order: `KITTY_WINDOW_ID` → OSC 99 (Kitty) →
`WT_SESSION` → Windows toast → OSC 777 (iTerm2, WezTerm, Ghostty).

Notification text: `Pi — Done (Ns)` where N is the rounded elapsed seconds.

### `ext-toggle.ts`

Registers `/ext` slash command. Opens a multi-toggle overlay built on
`SettingsList` from pi-tui. Lists files in `~/.pi/agent/extensions/` with
`● enabled` / `○ disabled` values. Space stages a toggle; Enter commits
all pending renames at once and calls `ctx.reload()`; Escape cancels.

**UX rationale:** the previous single-pick + immediate-apply flow made
it awkward to flip several extensions in a row (every toggle reloaded
the whole runtime). Stage-then-commit batches reloads to one per
session.

**Key design decisions:**

- **Rename, not delete.** Disabling a built-in produces a `name.ts.off`
  symlink/file that's invisible to pi's `*.ts` discovery glob but trivially
  reversible. No state stored elsewhere.
- **Symlink-friendly.** `fs.renameSync` renames the symlink itself; the repo
  target is untouched. Toggling an extension installed by this repo is
  reversible without re-running `install.sh`.
- **`install.sh` respects the disabled state.** When linking, the installer
  first checks for a `<name>.ts.off` symlink pointing into this repo and
  skips re-linking if found. So re-running `./install.sh` (e.g. to pick up
  a newly added extension) does not silently re-enable a previously
  `/ext`-disabled extension.
- **Per-extension disable guards.** A `DISABLE_GUARDS` map keyed by bare
  extension name lets specific extensions refuse a `/ext` disable when
  toggling would silently break in-flight session state. Currently used
  by `ssh-controlmaster`: refuses to disable while `--ssh` is in
  `process.argv`, because disabling tears down the ControlMaster (if we
  own it) and reverts read/write/edit/bash to the local filesystem while
  the system prompt still says we're on the remote. Add new entries here
  as similar foot-guns are discovered.
- **Subdir extensions are read-only in v1.** `name/index.ts` shapes show up in
  the listing with a `[dir]` tag but cannot be toggled — the cleanest disable
  for a directory would need a hidden-prefix or move-aside dance that adds
  more failure modes than it's worth for now.
- **`install.sh --uninstall` matches both `*.ts` and `*.ts.off`.** Means a
  disabled extension is still cleaned up on uninstall, regardless of which
  state it was left in.
- **Listing is recomputed on every `/ext` invocation.** No cache, no event
  subscription — cheap enough for the tens of files this directory will ever
  contain.

**API used:**

- `pi.registerCommand(name, { description, handler })` — registers `/ext`.
- `ctx.ui.custom<T>((tui, theme, kb, done) => Component)` — full-overlay
  with own keyboard handling. The wrapper component intercepts `enter`
  via `matchesKey(data, Key.enter)` before forwarding to `SettingsList`,
  which would otherwise consume Enter for value-cycling.
- `SettingsList` from pi-tui — the list itself. Cycles values on space
  (and on enter, but enter is intercepted upstream). `onChange` fires
  per cycle and is where staging happens.
- `getSettingsListTheme()` from pi-coding-agent — themed colors.
- `ctx.ui.notify(message, level)` — toast for post-commit status / errors.
- `ctx.reload()` — same reload as `/reload` command.

No flags, no `agent_*` event handlers — fully passive until `/ext` is invoked.

### `todo.ts`

Unchanged copy of upstream `examples/extensions/todo.ts` from
`pi-coding-agent` (the homebrew install at `/opt/homebrew/Cellar/...`).
Provides the agent with a `todo` tool (actions: list/add/toggle/clear)
and registers `/todos` for the user to inspect the list.

**Why copied, not symlinked:** symlinking would point at
`/opt/homebrew/Cellar/pi-coding-agent/<version>/libexec/...` which
rotates on every brew upgrade — fragile. Copy keeps it stable; we lose
upstream updates but gain reproducibility.

**State persistence:** the agent stores todo state in tool result
`details`, not an external file. Two useful properties: state survives
`pi --continue`/`--resume` because it lives in the session JSONL, and
`/fork` correctly forks the todo list along with the conversation.

**Refresh from upstream when needed:**

```bash
cp /opt/homebrew/Cellar/pi-coding-agent/*/libexec/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/todo.ts \
   ~/src/src_local/pi-extensions/extensions/todo.ts
# review diff, then commit
```

### `mcp-loader.ts`

Generic MCP client — reads an `mcp` block from `~/.pi/agent/settings.json`
and connects to each declared server (stdio subprocess or streamable-HTTP
endpoint), exposing the tools as namespaced pi tools.

**Why this exists:** pi has no built-in MCP loader (unlike opencode and Claude
Desktop). Adding each new MCP server as a hand-rolled extension (the way
`mempalace.ts` does it) doesn't scale past 2-3 servers. This loader is the
config-driven generalization — one extension, any number of servers, two
transports.

**Key design decisions:**

- **Settings.json shape matches opencode / Claude Desktop verbatim.** A user
  can copy-paste their `mcp` block from one harness's config to the other.
- **Tool names are prefixed with the server name** to avoid collisions when
  multiple servers expose tools with the same short name. Tools that already
  start with `<servername>_` (the convention some servers like mempalace
  follow internally) skip the prefix to avoid double-prefixing.
- **Tool names are sanitized to `^[A-Za-z][A-Za-z0-9_]{0,63}$`** before
  registering with pi. This is the strictest regex we have to satisfy:
  Anthropic's Messages API allows hyphens, but AWS Bedrock's Anthropic shim
  rejects them outright — a single hyphenated tool name causes the whole
  turn to 4xx silently, manifesting as "no output at all" once the offending
  server is enabled. context7 surfaces this because its tools are named
  `resolve-library-id` and `query-docs`. We replace any non-`[A-Za-z0-9_]`
  char with `_`, prepend `t_` if the result doesn't start with a letter, and
  truncate to 64 chars. The original MCP-side name is kept in the closure
  used by `client.callTool`, so the sanitization is purely pi-facing.
- **Fail-soft per server.** A server that won't start (binary missing, init
  handshake fails, remote 4xx/5xx) logs one stderr line and is skipped.
  Other servers continue. Pi keeps working.
- **Two transports behind one interface.** `IMcpClient` (`start`, `tools`,
  `callTool`, `stop`) is implemented by `StdioMcpClient` (subprocess +
  newline-delimited JSON-RPC) and `RemoteMcpClient` (HTTP POST + JSON or
  SSE response). The extension entry dispatches on `cfg.type` and the
  rest of the code is transport-agnostic.
- **Does not replace `mempalace.ts`.** The mempalace bridge has bespoke
  agent-identity injection from `$MEMPALACE_AGENT_NAME` that's worth
  preserving. Loader and bridge coexist. Listing `mempalace` in the `mcp`
  block would produce duplicate tool registrations — don't.
- **No stdio reconnect on death.** If a stdio subprocess crashes
  mid-session, its tools become permanently unavailable until pi `/reload`s.
  Same limitation as the mempalace bridge today.
- **Remote sessions self-heal on 404.** Per spec 2025-11-25 §2.2, a server
  that has terminated a session MUST respond with HTTP 404 to requests
  carrying the stale `Mcp-Session-Id`. `RemoteMcpClient` catches this
  condition (404 + sessionAtStart was non-null), drops the id, runs a fresh
  `initialize` + `notifications/initialized`, and retries the original
  request once. Persistent 404s after refresh surface as errors.

**API used:**

- `pi.registerTool({ name, label, description, parameters, execute })` for
  each MCP tool exposed by each connected server.
- `pi.on("session_shutdown", ...)` to SIGTERM stdio subprocesses and DELETE
  remote sessions cleanly.
- `Type.Unsafe<...>(inputSchema)` from typebox to pass the MCP server's
  JSON schema through to pi without conversion (TypeBox schemas are
  plain JSON Schema at runtime).

**Internal MCP clients:**

- `class StdioMcpClient` — spawn subprocess, write newline-delimited
  JSON-RPC, parse newline-delimited responses, match by request `id`.
  Stderr drained silently unless `PI_MCP_LOADER_DEBUG=1`.
- `class RemoteMcpClient` — streamable-HTTP per MCP spec 2025-03-26.
  POST JSON-RPC body to a single URL with `Accept: application/json,
  text/event-stream`. Server replies either with one JSON response or an
  SSE stream containing `event: message` / `data: <json>` blocks; we
  consume the stream until the response with our `id` arrives, then
  cancel the reader. Optional `Mcp-Session-Id` header is captured on
  initialize and round-tripped on every subsequent request, then DELETEd
  on stop. Per-server `headers` config (e.g. `Authorization`) is merged
  into every request. No GET-stream subscription — server-initiated
  notifications are not consumed.
- Both share `interface IMcpClient { serverName, tools, start, callTool, stop }`.
  Both send `initialize` handshake with `protocolVersion: MCP_PROTOCOL_VERSION`
  (currently `2025-11-25`, per the constant at the top of the file),
  then `notifications/initialized`, then `tools/list` to discover tools.

**Future extensions:**

- OAuth flow for remote servers that require it (today: pre-issued bearer
  tokens via `headers` only).
- Per-tool enable/disable in settings.json (e.g.
  `"mcp.searxng.tools": ["web_search"]` to expose only a subset).
- Reconnect-on-crash with exponential backoff.
- Schema sanitization for MCP servers that emit malformed `inputSchema`
  (some return `{type: "object", properties: {...}}` without `required`).

No framework. Manual:

```bash
./install.sh --help
./install.sh --yes                             # fresh install
./install.sh --yes                             # re-run (idempotent — all "already linked")
./install.sh --only ssh-controlmaster --yes   # subset
./install.sh --skip ssh-controlmaster --yes   # inverse subset
./install.sh --uninstall --yes                # remove
./install.sh --yes                             # reinstall
```

Manual extension tests (requires a reachable SSH host):

```bash
# Key-based auth
pi --ssh user@host

# Explicit remote path
pi --ssh user@host:/etc

# Password auth
pi --ssh user@host --ssh-ask-pass

# Verify status bar shows ⚡ own master or ⚡ system master
# Verify /reload works without restarting pi
```

## Gotchas

- **`ctx.ui.input()` does not mask input.** Passwords typed via `--ssh-ask-pass`
  are visible in the terminal. A masked alternative would require a custom
  `ctx.ui.custom()` component.
- **Socket path length limit on macOS.** Unix socket paths are capped at ~104
  characters. `/tmp/pi-cm-<pid>.sock` is safe. Don't use paths under `$HOME`
  which can be long.
- **`ssh -G` strips the `user@` prefix before querying config.** The `readSshConfig`
  helper does this automatically. Don't pass `user@host` directly to `ssh -G`.
- **`SSH_ASKPASS_REQUIRE=force` requires OpenSSH 8.4+.** `DISPLAY=dummy` is set
  as a fallback for older versions. Both are needed for full compatibility.
- **Extensions loaded globally affect every pi session.** Extensions without
  an activating flag (e.g. a `session_start` hook that always fires) will
  run on every invocation. Keep that surface small.
- **`pi install /path` and `install.sh` symlinks are mutually exclusive** for
  the same extension. `pi install` manages its own copy; `install.sh` manages
  a symlink. Pick one per machine.

## Related repos

- [`pi-toolkit`](https://gitea.jordbo.se/joakimp/pi-toolkit)
  — pi bring-up: settings template, keybindings, shell env loader. Install
  this first.
- [`mempalace-toolkit`](https://gitea.jordbo.se/joakimp/mempalace-toolkit)
  — persistent memory layer. Installs `mempalace.ts` into
  `~/.pi/agent/extensions/` separately from this repo.
- [`skillset`](https://gitea.jordbo.se/joakimp/skillset)
  — same pattern for agent skills rather than extensions.
- [`opencode-devbox`](https://gitea.jordbo.se/joakimp/opencode-devbox)
  — Docker containers; composes toolkits via independent install.sh calls.

## Documentation drift sweep

Before committing any non-trivial change, check that prose still matches code. Drift hotspots in this repo:

- `README.md` — the per-extension feature/usage descriptions, the install instructions, the dependency list. When an extension's flags or behaviour change, the README block for that extension is the first thing to update.
- `AGENTS.md` (this file) — the `Extension-specific notes` section is large and easy to leave stale. Each extension has its own subsection; if you change a flag, hook, or default, update the subsection here as well as the README.
- Extension files themselves — the `// description:` comment header pi parses for the extension list view must stay accurate.
- `install.sh` — `--only` / `--skip` defaults, the list of artifacts it knows about, and the symlink targets. If you add a new extension file, the installer's auto-discovery picks it up; if you add a new artifact type that needs special handling, the script must be updated and the README block describing what `install.sh does` along with it.

Quick triage: `git diff --name-only HEAD | xargs -I{} grep -l 'thing-you-changed' README.md AGENTS.md install.sh`. For an extension rename, also grep for the old name across the whole repo.