pi-tools

@senomas/pi-tools is a pi extension workspace (pi-coding-agent) that ships a small set of user-facing slash commands for interactive git and file workflows. The repo is planned, reviewed, and tracked in place — design specs live in docs/plan, review records in docs/review, and the work queue in todo/ — so the code, its history, and the reasoning behind each decision stay together.

From inside the repo, pi -e . loads the extension like any pi package: package.json → pi.extensions → src/pi-tools.ts. In this workflow every pi session is launched with -ne (auto-discovery off) plus explicit -e entries that include ., so the commands below are registered by the project extension, not by global auto-discovery files.

Commands

All commands are user-initiated slash commands (discoverable via /help), not LLM-callable tools. They require interactive TUI mode — in RPC/JSON/print modes they notify a warning and return.

| Command | What it does | | --- | --- | | /git [args...] | Launch lazygit (interactive git TUI) in ctx.cwd, suspending the pi TUI for the duration. Extra args are forwarded verbatim. lazygit missing → error notify with the install URL. | | /git log [git-log args...] | Leading-token subcommand: run git --no-pager log --decorate --graph --all --oneline headless (no TUI suspension) with trailing args appended, and deliver the captured commit graph to the user as a git-log-output transcript entry. User-only — the entry never reaches the LLM and starts no agent turn. Always rendered in the chat (see “Transcript entries”). | | /ed [file...] | Open file(s) (resolved against ctx.cwd) in $EDITOR (default vi), suspending the pi TUI. No path opens an empty scratch buffer. $EDITOR is used verbatim, so EDITOR="code --wait" works. | | /fe [path...] | Launch yazi (terminal file explorer) in ctx.cwd, suspending the pi TUI. yazi missing → error notify with the install URL. |

External binaries are located via which, with a probe of common install paths as fallback. Spawns run in the pi Node process (host), never in a container.

Transcript entries

/git log — and future capture-style subcommands — deliver their output as custom transcript entries (pi.appendEntry + pi.registerEntryRenderer) instead of raw terminal output. Custom entries do not participate in LLM context and never start an agent turn; they persist in the session and render in the interactive chat transcript.

Current entry type: git-log-output — the captured commit graph, rendered always-visible by a load-time renderer (so restored sessions render past entries too after /reload or /resume). Captures are size-bounded: stdout is capped at 128 KiB (git is stopped early on a giant history — bounded memory and runtime), stderr at 4 KiB; truncation is flagged in the entry.

Layout

graph TD
    subgraph pi session
        U["/git · /git log · /ed · /fe"]
        U --> E["pi-tools entry<br/>src/pi-tools.ts<br/>(registerGitEd + registerFe)"]
    end
    E --> GE["src/git-ed.ts<br/>/git → lazygit · /git log → capture"]
    E --> FE["src/fe.ts<br/>/fe → yazi"]
    GE --> TUI["src/tui-app.ts<br/>runTuiApp · notifyExit · splitArgs · findBinary"]
    FE --> TUI

• src/pi-tools.ts — single extension entry (default export), mirroring the pi-hat extension layout; new in-repo tools hook in here.
• src/tui-app.ts — shared TUI-suspension machinery (runTuiApp / notifyExit / splitArgs / findBinary), extracted so every launcher command shares one reviewed stop/start lifecycle.
• src/git-ed.ts — registerGitEd(pi): /git (lazygit + the /git log headless capture and its entry renderer) and /ed. Re-homed from the old global auto-discovery file ~/.pi/agent/extensions/git-ed.ts, which -ne sessions never load.
• src/fe.ts — registerFe(pi): /fe (yazi), built on the shared machinery.

Development workflow

This repo is managed pi-hat style, with role-tracked branches:

1. Planner writes the spec (docs/plan/*.md), queues tasks (todo/).
2. Implementor implements src/ per the spec and records the work.
3. Reviewer reviews the result (docs/review/*.md) and closes chains.
4. Role switches are explicit user actions; the current role lives in .pi/pi-hat.json (per-branch roles in .pi/branches.json).

Documents carry YAML frontmatter (type: plan | review, title, status, sources, created). Approved specs stay for history when superseded — e.g. docs/plan/git-log-subcommand.md is superseded by docs/plan/git-log-append-entry.md, which reworked /git log output from raw-terminal printing to transcript-entry delivery.

Roadmap

• /git rebase — approved plan (docs/plan/git-rebase.md): a /hat-style branch picker annotated with divergence (master (+5) ff), followed by a real git rebase <target> and a user-only git-rebase-result transcript entry. Conflict resolution is deliberately out of scope (resolved in lazygit via /git). Not yet implemented.

Requirements

• pi (pi-coding-agent) runtime with extension support.
• Node.js environment where pi runs (commands spawn in the host Node process).
• Optional external binaries (missing ones produce error notifies with install URLs, not crashes):
  • lazygit — for /git
  • yazi — for /fe
  • any $EDITOR — for /ed (defaults to vi)

License

MIT — see package.json.