Extensions

Extension	Description
bash-sane	Parsed bash approval gate with one-time, session, and persistent directory-scoped policies
bash-description	Cache-friendly optional model-generated summaries for bash tool calls, scoped by agent run
codex-web-search	Enables Codex web search by patching provider payloads for Codex models
codex-reset-credits	Lists and consumes banked Codex usage limit resets
bash-permission-gate.ts	Simple confirmation prompt before executing bash commands
block-sensitive-files.ts	Blocks access to sensitive files (.env, .envrc, etc.) and redacts sensitive env vars from tool results and bash outputs
agent-summary.ts	Shows a TUI-only summary of consulted (read) and changed (write/edit) files after each turn without adding it to LLM context
notify.ts	Desktop notifications when agent finishes (Ghostty, iTerm2, WezTerm, Kitty)
idle-inhibit.ts	Holds a systemd idle inhibitor while the agent is running (requires systemd-inhibit)
turn-timer.ts	Show live turn and session timing in status bar
followup.ts	Adds a /followup command to queue repeated follow-up user messages
vendored/read-mode.ts	Fullscreen read mode that scrolls conversation history with a pinned follow-up input (upstream: minghinmatthewlam/pi-read-mode)
vendored/tps.ts	Shows tokens-per-second performance metrics at end of agent run (upstream: badlogic/pi-mono)

Usage

Requires Pi extension API 0.81.1+ (@earendil-works/* packages).

# Single file extension
pi -e ./extensions/<name>.ts

# Directory extension
pi -e ./extensions/bash-sane
pi -e ./extensions/bash-description/index.ts
pi -e ./extensions/codex-web-search
pi -e ./extensions/codex-reset-credits/index.ts

# Multiple extensions
pi -e ./extensions/turn-timer.ts -e ./extensions/notify.ts

# Auto-load (copy to ~/.pi/agent/extensions/)
cp ./extensions/<name>.ts ~/.pi/agent/extensions/
cp -r ./extensions/bash-sane ~/.pi/agent/extensions/
cp -r ./extensions/bash-description ~/.pi/agent/extensions/
cp -r ./extensions/codex-web-search ~/.pi/agent/extensions/
cp -r ./extensions/codex-reset-credits ~/.pi/agent/extensions/
cp ./extensions/vendored/read-mode.ts ~/.pi/agent/extensions/
cp ./extensions/vendored/tps.ts ~/.pi/agent/extensions/

vendored/read-mode.ts upstream: https://github.com/minghinmatthewlam/pi-read-mode

vendored/tps.ts upstream: https://github.com/badlogic/pi-mono/blob/main/.pi/extensions/tps.ts

Or add to ~/.pi/agent/settings.json:

{
  "extensions": [
    "/path/to/repo/extensions/turn-timer.ts",
    "/path/to/repo/extensions/notify.ts"
  ]
}

bash-sane stores persistent rules in ~/.pi/agent/pi-bash-sane.policy.json. If you install extensions/bash-sane/ standalone, run npm install in that directory first. See extensions/bash-sane/SPEC.md for behavior and policy details.

codex-web-search keeps state in memory only. Use /codex-web-search for the native picker UI or /codex-web-search [off|cached|live] to set it directly. Default mode is cached.

codex-reset-credits requires the openai-codex ChatGPT OAuth login. Use /codex-resets to list banked resets and /codex-reset-burn to select, confirm, and consume one.

bash-description keeps a stable optional bash schema for prompt caching. Use /bash-description [on|off|next [N]|status]; state is session-local and defaults to off.

Template

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.on("event_name", async (event, ctx) => {
    // your code
  });
}

Prompts

Prompt	Description
slice-diff	Slice diffs atomically with git-hunk for Git or jj-hunk for jj
address-review-with-confirmation	Address review comments one by one after explicit confirmation

Invoke prompt templates in pi with /slice-diff or /address-review-with-confirmation.

Skills

Skill	Description
nix-search	Search and query NixOS packages and options using nix-search-tv
rust-crate-locator	Locate source code directory of Rust dependencies from the cargo registry cache
gitbook-scraper	Scrape GitBook documentation sites into Markdown files

Usage

Skills are loaded automatically by pi when placed in ~/.pi/agent/skills/ or referenced by path.

# Copy skill to pi's skills directory
cp -r ./skills/rust-crate-locator ~/.pi/agent/skills/

# Or reference by path (pi loads SKILL.md)
pi --skill ./skills/rust-crate-locator/SKILL.md

Skill Template

Skills are defined in SKILL.md files with frontmatter metadata:

---
name: skill-name
description: Brief description of when to use this skill
---

# Skill Title

Detailed documentation of the skill's purpose and usage.

Themes

Theme	Description
gruvbox-dark.json	Classic Gruvbox dark theme with warm earthy colors
gruvbox-material-dark-hard.json	Gruvbox Material dark hard variant with improved contrast