# Lelezonio Pi Kit

Personal Pi kit containing global extensions, themes, and bootstrap config.

Each extension is published as its own Pi extension entry so it can be enabled, disabled, or filtered independently.

## Extensions

### `lelezonio-pi-kit`

Adds `/setup` and `/preset` for managing which extensions from this personal Pi kit are loaded. `/setup` opens a checkbox-style menu: use arrow keys to navigate, `Space` to toggle extensions, `Enter` or `s` to save and reload, `a` for all extensions, `m` for the minimal profile, and `Esc` to cancel. The kit manager keeps itself enabled so you cannot lock yourself out.

Commands:

- `/setup` — open the extension checkbox menu.
- `/setup status` — show enabled/disabled kit extensions, package source, stale filters, and missing files.
- `/setup doctor` or `/doctor` — run a setup health check.
- `/setup enable <extension>` — enable one extension and reload.
- `/setup disable <extension>` — disable one extension and reload.
- `/setup toggle <extension>` — toggle one extension and reload.
- `/setup full` — enable every kit extension and reload.
- `/setup minimal` — enable the minimal default set and reload.
- `/setup save <name>` — save the current extension selection as a preset.
- `/setup use <name>` — apply a preset by name and reload.
- `/setup list` — list built-in and saved presets.
- `/setup delete <name>` — delete a saved preset.
- `/preset` — choose a setup preset from a picker.
- `/preset <name>` — apply a setup preset by name.
- `/preset save <name>` — save the current extension selection as a preset.
- `/preset delete <name>` — delete a saved preset.

### `codex-switcher`

Adds `/codex` for saving and switching between ChatGPT/Codex OAuth accounts. It stores account profiles in `~/.pi/agent/codex-accounts.json` (contains OAuth tokens; keep private), updates Pi's `openai-codex` credentials, and mirrors the matching Codex CLI auth file when available.

Commands:

- `/codex` — pick a saved Codex account from a selector.
- `/codex save <name>` — save the currently logged-in Codex account.
- `/codex use <name>` or `/codex <name>` — switch to a saved account.
- `/codex list` — list saved accounts.
- `/codex current` — show the current account marker without exposing tokens.
- `/codex delete <name>` — remove a saved account profile.

Typical setup: run `/login openai-codex`, `/codex save personal`, log into the second account, then `/codex save work`.

### `git-pr`

Adds a guarded GitHub pull request workflow. `/git <target-branch>` gathers read-only git snapshots, then sends the agent a structured PR workflow prompt that requires an explicit base branch, commit planning, PR description approval, push, and `gh pr create --base <target-branch>`. It also blocks `gh pr create` tool calls that omit `--base`, and asks before allowing a base branch different from the last `/git` target for that repo.

Commands:

- `/git <target-branch>` — plan commits, push, and create a GitHub PR against the target branch.
- `/yeet [instructions]` — add, inspect, commit, and push current repository changes.

### `pwsh-user-bash`

Replaces Pi's user `!` shell backend with PowerShell 7 on Windows-oriented setups. It runs `pwsh` directly, avoids the local Git Bash wrapper, keeps startup non-interactive, and optionally sources a dedicated Pi profile before each command.

Environment variables:

- `PI_USER_BASH_PWSH` or `PI_USER_BASH_SHELL` — override the PowerShell executable path.
- `PI_USER_BASH_PWSH_PROFILE` — override the profile script sourced before commands. Defaults to `$HOME/.config/powershell/pi-profile.ps1`.

### `diff`

Tracks files changed during the last agent run. It records the git status baseline at agent start, watches `edit`/`write` tool results, and reports changed files when the run ends. `/diff` opens an interactive changed-file picker and opens the selected file in Zed. It also owns `/zed` for opening the current working directory in Zed.

Commands:

- `/diff` — choose a changed file and open it in Zed.
- `/diff list` — print the tracked changed files.
- `/diff clear` — clear the tracked list and reset the git baseline.
- `/zed` — open the current directory in Zed.

### `theme-cycler`

Cycles installed themes without using Ctrl+Shift shortcuts that are commonly intercepted by Zed or terminal hosts. `/theme` opens a selector that previews themes in memory as you move through the list, without rewriting settings; `Enter` persists the previewed theme and `Esc` restores the previous theme. Override the defaults with `PI_THEME_NEXT_SHORTCUT` and `PI_THEME_PREVIOUS_SHORTCUT` if needed.

Commands and shortcuts:

- `/theme` — choose a theme from a picker.
- `/theme <name>` — switch directly to a theme.
- `Alt+]` — next theme.
- `Alt+[` — previous theme.

### `pi-ui`

Installs a custom Pi terminal UI with a responsive Pi header, configuration-aware shortcut hints, a compact footer showing model/provider/thinking, clickable path, git branch/dirty/PR status, relevant extension statuses, and context usage, plus a one-line last-user-message row, custom editor border colors, fixed editor layout support, and live working-phase/duration feedback. No session title, token-speed, monetary-cost, or display-awake indicators are shown. When the RunCat font is installed, the fixed-editor activity border animates it and replaces Pi's redundant built-in working row. It also adds an editor text stash shortcut.

Commands:

- `/pi-ui` — enable the custom header/footer and fixed editor for the current session.
- `/pi-ui-safe` — keep the custom header/footer while using Pi's standard editor.
- `/pi-ui-builtin` — restore Pi's built-in header/footer/editor UI for the current session.

Set `PI_UI_FIXED_EDITOR=0` to start in safe mode by default. Set `PI_UI_RUNCAT=0` to hide RunCat, or `PI_UI_RUNCAT=1` to enable it when your terminal uses the RunCat font. Header branding uses the active theme's semantic colors by default; set `PI_UI_GRADIENT=1` to opt into the animated per-character gradient.

Shortcuts:

- `Alt+S` — stash the current editor text; press again with an empty editor to restore it.

### `usage-bar`

Adds an interactive `/usage` overlay with AI provider quota bars, reset countdowns, plan details, and provider status indicators for Claude, GitHub Copilot, OpenCode Go, and Codex/OpenAI where credentials are available.

Commands:

- `/usage` — show usage/quota bars and provider status. Press any key to close.

### `background-terminals`

Lets the LLM agent manage background shell processes with tools `bg_start`, `bg_status`, `bg_list`, and `bg_kill`, and provides a `/ps` TUI overlay for the user. Supports up to 8 running terminals with 32 completed retained. Output is auto-delivered to the agent on terminal exit. Uses PowerShell for process tree management on Windows. The included `background-terminals` skill teaches the agent when to start, inspect, and stop long-lived commands without wasteful polling.

Commands:

- `/ps` — interactive overlay with live terminal list and detail view.
- `/ps kill <id>` — kill a specific terminal.
- `/ps killall` — kill all terminals.

### `subagents`

Provides the `subagent_spawn`, `subagent_wait`, `subagent_cancel`, `subagent_check`, and `subagent_list` tools. Supports Pi and Codex harnesses with configurable model resolution, thinking levels, and concurrency (max 4). Background agents run asynchronously, store run metadata under the task working directory's `.pi/output/`, and deliver one-shot completion follow-ups. The included `subagents` skill documents both the non-blocking headless workflow and visible Herdr agents.

#### Visible Herdr agents

The bootstrap installs `npm:@ogulcancelik/pi-herdr@0.4.0`. When Pi is running inside Herdr, requests for a Herdr pane or a visible, interactive, or interactable subagent use `herdr_layout` and `herdr_agent` instead of `subagent_spawn`. The parent creates a sibling pane, starts the requested coding agent, sends a self-contained prompt, waits for lifecycle settlement, and reads the result. Headless `subagent_spawn` remains the default when no visible interface is requested.

Herdr itself is not bundled. Install Herdr 0.7.5 or newer separately and start Pi inside a Herdr-managed pane. The tools activate only when `HERDR_ENV=1` and `HERDR_PANE_ID` are present.

#### Subagents configuration

Create `~/.pi/agent/subagents.json` to configure per-harness defaults and reusable named profiles:

```json
{
  "defaultHarness": "pi",
  "maxConcurrent": 4,
  "harnesses": {
    "pi": {
      "model": "opencode-go/glm-5.2",
      "thinking": "max"
    },
    "codex": {
      "model": "gpt-5.6-sol",
      "thinking": "high"
    }
  },
  "profiles": {
    "planner": {
      "harness": "codex",
      "model": "gpt-5.6-sol",
      "thinking": "high"
    },
    "coder": {
      "harness": "pi",
      "model": "opencode-go/kimi-k2.7-code",
      "thinking": "high"
    },
    "reviewer": {
      "harness": "pi",
      "model": "opencode-go/deepseek-v4-flash",
      "thinking": "high"
    }
  },
  "codex": {
    "sandbox": "workspace-write",
    "path": "codex",
    "maxEffort": "high"
  },
  "trust": {
    "restrictCwd": false,
    "allowedDirs": []
  }
}
```

Pass a profile with `subagent_spawn({ profile: "coder", task: "..." })`. Explicit `harness`, `model`, `thinking`, `codexSandbox`, or `maxTurns` fields on the spawn call override the profile; profile values override per-harness defaults. An unknown profile name fails immediately instead of silently falling back.

**Model resolution**: Pi-harness model values use `provider/modelId` and are resolved dynamically through `ctx.modelRegistry.find(provider, modelId)`. This includes OpenCode Go models such as `opencode-go/kimi-k2.7-code`; when omitted, the child inherits the parent session model. Codex-harness model values are optional Codex CLI model slugs; when omitted, the CLI chooses its configured default. Set `codex.path` or `CODEX_PATH` to override the Codex executable. Each Codex child uses its own temporary `CODEX_SQLITE_HOME`, avoiding app-server startup failures caused by shared SQLite locks while continuing to use the normal Codex auth and configuration.

Commands:

- `/subagents` — TUI overlay for viewing and cancelling subagent runs.
- `/btw` — background task watch.

### `workflows`

Executes multi-step agent pipeline scripts via the `workflow` tool with foreground and background modes. Scripts use a Davis-style DSL:

```js
export const meta = { name: "my workflow", description: "...", phases: ["plan", "build"] };
phase("plan");
await agent("Research the codebase", { label: "research", model: "openai-codex/gpt-5.6-luna" });
await parallel([
  () => agent("Task A", { label: "A" }),
  () => agent("Task B", { label: "B" }),
], { concurrency: 2 });
```

Supports up to 32 agent calls with max 4 concurrent. The optional `args` parameter accepts a JSON object exposed to scripts as the frozen global `args`. Model defaults from the session context; thinking level from Pi's global setting. Background runs return immediately with a run ID and deliver results via follow-up message. Artifacts are stored under `~/.pi/agent/workflows/<runId>/`.

Commands:

- `/workflows` — dashboard TUI overlay for managing workflow runs.
- `/workflows list` — list all runs.
- `/workflows inspect <id>` — view full progress and output.
- `/workflows cancel <id>` — cancel a running workflow.
- `/workflows delete <id>` — delete stored artifacts.
- `/workflows run <script>` — validate and load a workflow script.

### `ask-user`

Registers the `ask_user` tool that lets the LLM ask the user an interactive question with optional multiple-choice options (2-5), freeform text, and cancellation. Renders a custom TUI overlay when available; falls back to dialog-based input in headless mode. Runs in sequential execution mode to prevent batching with side-effecting tools.

### `file-search`

First-class `fd` and `rg` tools for agent file and content search. On session start, resolves a usable binary: existing system binaries are preferred, `~/.pi/agent/bin/` fallbacks checked silently, and official releases downloaded with SHA256 verification only when neither exists. Supports Linux (x64, arm64), macOS (x64, arm64), and Windows (x64, arm64).

### `copy-all`

Registers the `/copy-all` command that copies all user and assistant messages from the current conversation branch to the system clipboard. Cross-platform clipboard support (PowerShell/clip.exe on Windows, pbcopy on macOS, wl-copy/xclip/xsel on Linux). Falls back to writing a temp file when no clipboard tool is available.

Commands:

- `/copy-all` — copy the current branch conversation to clipboard.

## External extensions installed by the bootstrap

### `pi-review-loop`

Installs Earendil Works' persistent incremental diff reviewer. `/diff-review` opens a native review window that compares the current workspace with either `HEAD` or the last session-backed review checkpoint. Inline and file-level comments are composed into feedback and inserted into Pi's editor for inspection before submission.

Commands:

- `/diff-review` — open or focus the review window.

The extension is installed from `git:github.com/earendil-works/pi-review-loop`. Do not substitute the unrelated `npm:pi-review-loop` package.

## Themes

Included themes:

- `github-dark-default`
- `pi-electric-aurora`
- `pi-ocean-glass`
- `pi-synthwave`
- `pi-terminal-emerald`
- `pi-royal`

## Install on a new machine

Install Pi first:

```bash
npm install -g @earendil-works/pi-coding-agent
```

Then install this kit from npm:

```bash
npx lelezonio-pi-kit
```

Alternatively, with Pi's package manager:

```bash
pi install npm:lelezonio-pi-kit
```

The npm bootstrap adds these packages to `~/.pi/agent/settings.json`:

- `npm:pi-hermes-memory` — long-term memory storage and retrieval.
- `npm:pi-extmgr` — extension management utilities.
- `npm:lelezonio-pi-kit` — this kit.
- `npm:pi-runcat` — optional RunCat font and fallback working indicator; `pi-ui` moves the cat into its fixed-editor activity border when the font is installed.
- `npm:@ogulcancelik/pi-herdr@0.4.0` — structured tools for Herdr workspaces, panes, terminal processes, and visible coding agents.
- `git:github.com/earendil-works/pi-review-loop` — persistent incremental workspace review with session-backed checkpoints.

## Windows notes

- `pwsh-user-bash` replaces the `!` shell backend with PowerShell 7. Set `PI_USER_BASH_PWSH` to override the executable path.
- `background-terminals` runs commands through PowerShell (`pwsh.exe`, with `powershell.exe` fallback) and terminates process trees with `taskkill /T`, escalating to `/F`.
- `file-search` auto-downloads Windows x64/arm64 binaries for fd and rg.
- `copy-all` uses PowerShell `Set-Clipboard` (preferred) with `clip.exe` fallback.
- All path comparisons are case-insensitive on Windows.
- The Codex harness resolves npm's `codex.cmd` wrapper to its JavaScript entrypoint and launches it with Node, preserving the app-server's stdio JSONL pipes. Each child also gets an isolated temporary SQLite runtime.
- Herdr's Windows agent launcher may resolve npm's extensionless or PowerShell shim before the valid `pi.cmd` or `codex.cmd` launcher and fail with `%1 is not a valid Win32 application`. Prefer a Herdr release containing the launcher fix; until then, ensure the relevant `.cmd` wrapper resolves first rather than deleting npm-managed shims.

## External research

This kit uses **ketch** CLI for all external research — web pages, OSS code, and library docs. No other web search or scraping tools are configured. The agent prompt instructs the model to use ketch exclusively:

- `ketch search "query"` — web search with titles, URLs, snippets.
- `ketch search "query" --scrape` — search with full page content.
- `ketch scrape <url>` — fetch a URL as clean markdown.
- `ketch code "query" --lang go` — real OSS code search with line + repo + stars.
- `ketch docs "query" --library /org/repo` — version-aware library documentation.

## Development checks

```bash
npm ci
npm run typecheck
npm test
```

## Publishing

Pushing to `main` automatically bumps `package.json` by one patch version, commits/tags that release, and publishes `npm:lelezonio-pi-kit`.

Repository setup required once: add an `NPM_TOKEN` repository secret with publish access for the package. Add `[skip npm]` to a commit message to skip the publish workflow.