pi-toolbox

A comprehensive extension toolkit for the Pi Coding Agent — 17 extensions, 11 themes, skills, agents, and team orchestration templates.

🎬 Watch pi-toolbox in action

---

Installation

# Install globally
pi install npm:pi-toolbox

# Or project-local (shareable via git)
pi install -l npm:pi-toolbox

# Or try without installing
pi -e npm:pi-toolbox

Selective Loading

Load only specific extensions via settings.json:

{
  "packages": [
    {
      "source": "npm:pi-toolbox",
      "extensions": [
        "+extensions/minimal.ts",
        "+extensions/theme-cycler.ts",
        "+extensions/damage-control.ts"
      ],
      "themes": [],
      "skills": []
    }
  ]
}

---

Setup: Agents & Configs

Extensions like agent-team, agent-chain, system-select, and damage-control read agent definitions and configs from your project's .pi/ directory. Run the setup script to copy the bundled templates:

# From your project root
npx pi-toolbox setup

# Or manually
bash node_modules/pi-toolbox/setup.sh

This copies:

• 8 agent personas → .pi/agents/*.md (scout, planner, builder, reviewer, documenter, red-team, plan-reviewer, bowser)
• 10 Pi Pi experts → .pi/agents/pi-pi/*.md (ext, theme, skill, config, tui, prompt, agent, keybinding, cli experts)
• Team rosters → .pi/agents/teams.yaml
• Pipeline chains → .pi/agents/agent-chain.yaml
• Safety rules → .pi/damage-control-rules.yaml

Existing files are never overwritten. Delete a file first to get the latest version.

---

Extensions

UI & Footer

Extension	Description	Usage
pure-focus	Removes footer and status line entirely — distraction-free mode	pi -e extensions/pure-focus.ts
minimal	Compact footer: model name + 10-block context meter [###-------] 30%	pi -e extensions/minimal.ts
tool-counter	Rich two-line footer: model + context + token/cost stats + per-tool call tally	pi -e extensions/tool-counter.ts
tool-counter-widget	Live-updating above-editor widget with per-tool call counts and background colors	pi -e extensions/tool-counter-widget.ts
theme-cycler	Cycle themes with Ctrl+X / Ctrl+Q or /theme picker. Shows color swatch.	pi -e extensions/theme-cycler.ts
session-replay	/replay opens a scrollable timeline overlay of session history	pi -e extensions/session-replay.ts

Workflow & Discipline

Extension	Description	Usage
purpose-gate	Prompts you to declare session intent on startup. Blocks prompts until answered.	pi -e extensions/purpose-gate.ts
tilldone	Task discipline system — define tasks before working. Tracks completion with live progress.	pi -e extensions/tilldone.ts

Multi-Agent Orchestration

Extension	Description	Usage
agent-team	Dispatcher orchestrator with team select and grid dashboard. Primary agent delegates via dispatch_agent.	pi -e extensions/agent-team.ts
agent-chain	Sequential pipeline orchestrator — chains agents where each step's output feeds the next.	pi -e extensions/agent-chain.ts
subagent-widget	/sub <task> spawns background subagents with live streaming progress widgets.	pi -e extensions/subagent-widget.ts
pi-pi	Meta-agent that builds Pi agents with parallel expert research.	pi -e extensions/pi-pi.ts

Cross-Agent & Safety

Extension	Description	Usage
cross-agent	Scans .claude/, .gemini/, .codex/ dirs and registers their commands, skills, and agents in Pi.	pi -e extensions/cross-agent.ts
system-select	/system to interactively switch agent personas/system prompts.	pi -e extensions/system-select.ts
damage-control	Real-time safety auditing — intercepts dangerous bash patterns, enforces path access controls.	pi -e extensions/damage-control.ts

Code Review

Extension	Description	Usage
go-review	Reviews Go code changes against the 100 Go Mistakes checklist. Custom TUI rendering.	pi -e extensions/go-review.ts

---

Stacking Extensions

Extensions compose — pass multiple -e flags:

# Minimal footer + theme cycling
pi -e extensions/minimal.ts -e extensions/theme-cycler.ts

# Agent team with theme cycling
pi -e extensions/agent-team.ts -e extensions/theme-cycler.ts

# Subagent spawner + distraction-free + theme cycling
pi -e extensions/subagent-widget.ts -e extensions/pure-focus.ts -e extensions/theme-cycler.ts

# Task discipline + safety auditing + minimal footer
pi -e extensions/tilldone.ts -e extensions/damage-control.ts -e extensions/minimal.ts

---

Themes

11 hand-crafted themes with all 51 Pi color tokens:

Theme	Vibe
synthwave	Neon pink/cyan retro-futuristic
catppuccin-mocha	Warm pastel dark
cyberpunk	Electric neon futuristic
dracula	Classic purple-accented dark
everforest	Calm forest greens
gruvbox	Earthy warm retro
midnight-ocean	Deep navy blue
nord	Arctic cool blues
ocean-breeze	Light oceanic teal
rose-pine	Warm muted rose
tokyo-night	Sharp Tokyo neon

Each extension auto-loads its assigned theme on boot. Use /theme or Ctrl+X/Ctrl+Q (with theme-cycler) to switch.

---

Skills

Bowser — Playwright Browser Automation

Headless browser automation using playwright-cli. Supports parallel sessions, persistent profiles, and vision mode.

/skill:bowser

Features:

• Headless by default, --headed for visible browser
• Named sessions (-s=<name>) for parallel instances
• Persistent cookies and storage state
• Screenshots, PDF export, network interception

---

Agents

Core Agents

Agent	Role	Tools
scout	Fast recon and codebase exploration	read, grep, find, ls
planner	Architecture and implementation planning	read, grep, find, ls
builder	Implementation and code generation	read, write, edit, bash, grep, find, ls
reviewer	Code review and quality checks	read, bash, grep, find, ls
documenter	Documentation and README generation	read, write, edit, grep, find, ls
red-team	Security and adversarial testing	read, bash, grep, find, ls
plan-reviewer	Critically evaluates implementation plans	read, grep, find, ls
bowser	Headless browser automation via Playwright	bash

Pi Pi Experts (Meta-Agent Team)

Expert	Domain
ext-expert	Extensions — tools, events, commands, rendering
theme-expert	Themes — JSON format, 51 color tokens, vars
skill-expert	Skills — SKILL.md packages, scripts, frontmatter
config-expert	Settings — settings.json, providers, models, packages
tui-expert	TUI — components, overlays, widgets, footers
prompt-expert	Prompt templates — .md format, arguments
agent-expert	Agent definitions — personas, teams.yaml, orchestration
keybinding-expert	Keyboard shortcuts — Key IDs, reserved keys, compatibility
cli-expert	CLI — flags, modes, environment variables

Team Rosters (teams.yaml)

Team	Members
full	scout, planner, builder, reviewer, documenter, red-team
plan-build	planner, builder, reviewer
info	scout, documenter, reviewer
frontend	planner, builder, bowser
pi-pi	ext-expert, theme-expert, skill-expert, config-expert, tui-expert, prompt-expert, agent-expert

Agent Chains (agent-chain.yaml)

Chain	Flow	Description
plan-build-review	planner → builder → reviewer	Standard development cycle
plan-build	planner → builder	Fast two-step without review
scout-flow	scout → scout → scout	Triple-scout deep recon
plan-review-plan	planner → plan-reviewer → planner	Iterative planning with critique
full-review	scout → planner → builder → reviewer	End-to-end pipeline

---

Safety: Damage Control

The damage-control extension provides real-time security hooks:

• Dangerous Commands — regex patterns block rm -rf, git reset --hard, DROP DATABASE, AWS/GCP/Firebase destructive ops
• Zero Access Paths — blocks all access to .env, ~/.ssh/, *.pem, *.tfstate, credentials files
• Read-Only Paths — allows reading but blocks modifying lockfiles, build outputs, /etc/
• No-Delete Paths — allows modifying but prevents deleting .git/, LICENSE, README.md, Dockerfile

Rules are defined in .pi/damage-control-rules.yaml (run npx pi-toolbox setup to install).

---

Color Language

Extensions follow a consistent color convention:

Token	Role	Used For
success	Primary value	Counts, hash fills, branch names
accent	Secondary value	Percentages, tool names
warning	Punctuation/frame	Brackets, parens, pipes, cost
dim	Filler/spacing	Dashes, labels, separators
muted	Subdued text	CWD name, fallback states

---

Prerequisites

Tool	Purpose	Install
Bun ≥ 1.3.2	Runtime & package manager	bun.sh
pi	Pi Coding Agent CLI	Pi docs

---

Resources

• Pi Coding Agent — the agent framework
• Extensions docs — extension API reference
• Skills docs — skill format reference
• Themes docs — theme format reference
• Tactical Agentic Coding — master agentic coding patterns
• IndyDevDan YouTube — video tutorials

---

License

MIT