pi-gadget

A small collection of single-file pi extensions — handy gadgets, each living in one file:

• /clear — archive the current session (moves it out of the way while keeping it resumable)
• /exit — exit pi cleanly
• pi-cite-wslpath — tool for the model: converts native (WSL) paths into Windows-Terminal-openable markdown hyperlinks, because file:///home/... / file:///mnt/c/... links are rejected by Windows Terminal. Takes a paths[] batch in one call; an agent_end hook force-checks every delivered reply for un-converted links and posts a clickable report (detect-and-tell)

Install

pi install npm:@yceachan/pi-gadget

Usage

Run /clear to archive the active session, /exit to quit pi. Both commands are plain slash-command extensions; see the source files for exact behavior.

pi-cite-wslpath is a tool the model calls to cite file paths clickable in Windows Terminal (Ctrl+click). Conversion rules: /mnt/<drive>/... → file:///<DRIVE>:/..., other Linux paths → file://wsl.localhost/<distro>/... (Windows Terminal ≥ 1.17). Outside WSL it falls back to the standard file:// URI.

The tool takes a paths array (one or more native paths) and returns exactly one markdown link per path ([label](uri)), which the model pastes verbatim into its reply — pi's Markdown renderer turns it into an OSC 8 hyperlink, so it stays clickable at any terminal width (the URL is hidden on screen and the terminal reconstructs the link across soft wraps). Raw OSC 8 sequences and bare URIs are deliberately not returned: a bare URI is long, wraps on narrow screens, and Windows Terminal's URL auto-detection cannot join the fragments. Each path is verified to exist on disk; a missing path gets a ! not found line so a misspelled filename is caught at cite time, before the link is delivered.

On agent_end the extension force-checks the delivered assistant text for file:// URIs Windows Terminal would reject (empty-host file:///... or file://localhost with a non-drive first segment, i.e. Linux-side paths). When any leaked, it reports rather than rewrites, delivering on agent_settled (the moment the run is fully settled — sending during agent_end would otherwise be queued by pi as a steering message): a one-line notify summary plus a chat custom message (>[!note] pi-cite-wslpath auto trans: with the converted markdown links) rendered by the same Markdown → OSC 8 pipeline as the chat body, so every link is clickable regardless of terminal width. Quoted examples are skipped (code spans, fenced code blocks, and ... ellipsis forms), so citing the guideline text itself does not trip the check.

Configuration

Each gadget is enabled by default. Disable one in the user or project config:

{
  "pi-cite-wslpath": { "status": "disabled" }
}

Configuration layers are merged from low to high priority:

<package>/config.json
$PI_AGENT_DIR/pi-gadget/config.json      (or $PI_CODING_AGENT_DIR; default: ~/.pi/agent/pi-gadget/config.json)
$CWD/.pi/pi-gadget/config.json

The keys are pi-clear, pi-exit, and pi-cite-wslpath. A project setting overrides the user setting for the same key; omitted keys keep the lower-layer value. Changes take effect after /reload.

Use /gadgets to manage the current project's overrides:

/gadgets list
/gadgets enable pi-cite-wslpath
/gadgets disable pi-cite-wslpath
/gadgets enable --global pi-cite-wslpath
/gadgets disable --global pi-cite-wslpath

enable and disable update $CWD/.pi/pi-gadget/config.json and reload the extensions. With --global, the command updates the agent directory config; when the current project already has a config file, it updates that file too so the project override does not mask the global setting. If the project config is absent, it is left absent. The management command remains available while individual gadgets are disabled.

License

MIT