# pi-toolbox

A comprehensive extension toolkit for the [Pi Coding Agent](https://github.com/mariozechner/pi-coding-agent) — **17 extensions**, **11 themes**, **skills**, **agents**, and **team orchestration templates**.

> 🎬 Watch [pi-toolbox in action](https://youtu.be/f8cfH5XX-XU)

---

## Installation

```bash
# 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`:

```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:

```bash
# 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:

```bash
# 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.

```bash
/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](https://bun.sh) |
| **pi** | Pi Coding Agent CLI | [Pi docs](https://github.com/mariozechner/pi-coding-agent) |

---

## Resources

- [Pi Coding Agent](https://github.com/mariozechner/pi-coding-agent) — the agent framework
- [Extensions docs](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/extensions.md) — extension API reference
- [Skills docs](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/skills.md) — skill format reference
- [Themes docs](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/themes.md) — theme format reference
- [Tactical Agentic Coding](https://agenticengineer.com/tactical-agentic-coding?y=pivscc) — master agentic coding patterns
- [IndyDevDan YouTube](https://www.youtube.com/@indydevdan) — video tutorials

---

## License

MIT