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