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 (bring-up, keybindings, env loader) — that repo gets pi running; this repo adds behaviour on top of it. Also related to skillset which does the same job for agent skills.

Read 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)
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

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

require_pi_installed — aborts with exit 4 if ~/.pi/agent/ is missing. Creates ~/.pi/agent/extensions/ proactively.
Calls build_install_set to resolve which extensions to install based on --only / --skip flags (default: all .ts files in extensions/).
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

Drop a .ts file into extensions/. No other config needed — install.sh discovers all .ts files automatically.
Export a default factory function (pi: ExtensionAPI) => void. See the pi extensions docs and built-in examples.
Register any CLI flags via pi.registerFlag() so they appear in pi --help.
Keep the extension inert without its flag (or equivalent trigger). Don't run side effects unconditionally at load time.
Update README.md — add an entry under the Extensions section documenting flags, use cases, requirements, and how it works.
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.

Testing

No framework. Manual:

./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):

# 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.

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

8.0 KiB Raw Blame History