# pi-agent-config

Personal [pi](https://pi.dev) coding agent configuration: safety extensions, subagent definitions, skills, and prompt templates for a more powerful AI-assisted development workflow.

Fork this repo, adjust to taste, and get the same environment on any machine with two commands.

---

## What's included

### Extensions

Extensions are TypeScript modules that hook into pi's event system to add tools, commands, and safety guards. They load at startup.

This repo contains two groups of extensions:

- **Bundled** — copied directly into `extensions/` and installed with this package
- **External** — published as standalone npm/git packages and installed by the bootstrap script

#### Why are the badlogic extensions copied instead of installed directly?

The official pi extensions live in [badlogic/pi-mono](https://github.com/badlogic/pi-mono) under `packages/coding-agent/examples/extensions/`. That directory is part of a larger monorepo whose root `package.json` does not expose the examples as a standalone installable pi package. Running `pi install git:github.com/badlogic/pi-mono` would either fail or install the wrong thing. There is no published npm package for just the examples.

The correct and only reliable approach is to copy the files directly. They are MIT licensed and the source is attributed in the table below. This also means you have full control over them and can modify them freely without depending on upstream changes.

#### Bundled extensions

| Name | Category | What it does | Author |
|------|----------|--------------|--------|
| `permission-gate` | Safety | Prompts for confirmation before dangerous shell commands (`rm -rf`, `sudo`, `chmod 777`) | [badlogic/pi-mono](https://github.com/badlogic/pi-mono) |
| `protected-paths` | Safety | Blocks reads and writes to sensitive paths (`.env`, `.git/`, `node_modules/`) | [badlogic/pi-mono](https://github.com/badlogic/pi-mono) |
| `confirm-destructive` | Safety | Asks for confirmation before clearing or switching sessions | [badlogic/pi-mono](https://github.com/badlogic/pi-mono) |
| `dirty-repo-guard` | Safety | Warns when the repo has uncommitted changes before an agent run | [badlogic/pi-mono](https://github.com/badlogic/pi-mono) |
| `questionnaire` | Workflow | Lets the agent ask structured clarifying questions with a tab-based UI | [badlogic/pi-mono](https://github.com/badlogic/pi-mono) |
| `git-checkpoint` | Workflow | Creates a git stash checkpoint before each turn so `/fork` can restore the code state | [badlogic/pi-mono](https://github.com/badlogic/pi-mono) |
| `plan-mode` | Workflow | Read-only exploration mode: the agent proposes a numbered plan before touching files. Toggle with `/plan` or `Ctrl+Alt+P` | [badlogic/pi-mono](https://github.com/badlogic/pi-mono) |
| `subagent` | Workflow | Delegates tasks to specialized agents in isolated context windows (single / parallel / chain modes) | [badlogic/pi-mono](https://github.com/badlogic/pi-mono) |

#### External extensions

Installed automatically by the bootstrap script. Each one is a separate published package.

| Name | Install | What it does | Author |
|------|---------|--------------|--------|
| `commit-message` | [`npm:pi-commit-message`](https://www.npmjs.com/package/pi-commit-message) | `/commit` command: generates a Conventional Commits message from staged diff, shows a confirmation UI, and commits | [s1lver091/pi-commit-message](https://github.com/s1lver091/pi-commit-message) |

### Skills

Skills are Markdown capability packages (`SKILL.md`) loaded on demand. The agent reads the skill's description at startup and loads the full content only when it is relevant to the task. Invoke explicitly with `/skill:name` or let the agent recognize when to use them.

| Name | What it does | Author |
|------|--------------|--------|
| `code-review` | Structured code review process: correctness, security, performance, maintainability | [s1lver091](https://github.com/s1lver091/) |
| `debug` | Systematic debugging: reproduce, isolate, hypothesize, verify, fix | [s1lver091](https://github.com/s1lver091/) |
| `refactor` | Safe refactoring methodology: understand first, small steps, behavior preserved | [s1lver091](https://github.com/s1lver091/) |
| `plan` | Pre-implementation planning: explore codebase, identify approach, produce actionable steps | [s1lver091](https://github.com/s1lver091/) |
| `spec` | Technical specification writing: goals, data model, API design, edge cases, security | [s1lver091](https://github.com/s1lver091/) |
| `test` | Test writing methodology: identify cases, write meaningful assertions, verify coverage | [s1lver091](https://github.com/s1lver091/) |

### Subagents

Subagents run in isolated pi processes with their own context window. The `subagent` extension loads them from `~/.pi/agent/agents/`. Models are not hardcoded: each agent inherits the model active in your pi session.

| Name | Role | Author |
|------|------|--------|
| `scout` | Fast codebase recon: explores code and returns compressed, structured context for handoff | [s1lver091](https://github.com/s1lver091/) |
| `planner` | Converts scout output and requirements into a concrete, numbered implementation plan | [s1lver091](https://github.com/s1lver091/) |
| `worker` | Autonomous implementation agent with full tool access | [s1lver091](https://github.com/s1lver091/) |
| `reviewer` | Senior code reviewer focused on correctness, security, and maintainability (read-only) | [s1lver091](https://github.com/s1lver091/) |

### Prompt templates

Prompt templates live in `prompts/` and become slash commands in pi. Each template wires together a multi-agent chain via the `subagent` tool. Use `$@` to pass arguments.

| Command | Pipeline | Author |
|---------|---------|--------|
| `/implement <task>` | scout > planner > worker: full pipeline from discovery to implementation | [s1lver091](https://github.com/s1lver091/) |
| `/scout-and-plan <task>` | scout > planner: explore and produce a plan without touching any files | [s1lver091](https://github.com/s1lver091/) |
| `/implement-and-review <task>` | worker > reviewer > worker: implement, code review, apply feedback | [s1lver091](https://github.com/s1lver091/) |
| `/fix <bug>` | scout > worker: fast bug fix, skips planning for speed | [s1lver091](https://github.com/s1lver091/) |
| `/review [scope]` | reviewer: standalone code review on the current git diff | [s1lver091](https://github.com/s1lver091/) |

---

## Skills vs Prompt templates

| | Skills | Prompt templates |
|--|--------|-----------------|
| Trigger | `/skill:name` or automatic | Slash command (`/implement`) |
| Arguments | No | Yes (`$@`) |
| Use case | Reusable methodology in any session | Fixed workflow with specific steps |
| Example | "review this PR" uses `code-review` skill | `/implement add dark mode` triggers 3-agent chain |

---

## Installation

### Prerequisites

- [pi](https://pi.dev) installed and available as `pi` in your terminal
- A model provider configured (Anthropic, GitHub Copilot, Openrouter, etc.)
- Git installed

There are two ways to install: via the bootstrap script (recommended) or manually step by step.

---

### Option A: bootstrap script (recommended)

The bootstrap script handles everything in one shot: installs all packages and copies the agent definitions.

**1. Fork and clone this repo**

Fork it to your own GitHub account, then clone it locally:

```bash
git clone https://github.com/<your-username>/pi-agent-config.git
cd pi-agent-config
```

**2. Run the bootstrap**

macOS / Linux:
```bash
bash scripts/bootstrap.sh
```

Windows (PowerShell):
```powershell
.\scripts\bootstrap.ps1
```

**3. Restart pi** and you're done.

---

### Option B: manual install

If you don't want to clone the repo, you can install directly from npm or git and handle the agents separately.

**Install from npm:**
```bash
pi install npm:pi-agent-config
pi install npm:pi-commit-message
```

**Or from git:**
```bash
pi install git:github.com/<your-username>/pi-agent-config
pi install npm:pi-commit-message
```

**Then copy the agent definitions manually:**

The `subagent` extension requires agent `.md` files in `~/.pi/agent/agents/`. Clone the repo just to get them, or copy the files from `agents/` manually to that directory.

**Restart pi** to load everything.

---

### Verify

- Type `/plan`: plan mode should toggle on (status bar shows `plan`)
- Type `/implement fix the login bug`: the 3-step subagent chain should launch
- Type `/commit`: the commit message generator should open
- Ask the agent to "review the last changes": it should load the `code-review` skill automatically
- Run a dangerous command via bash: the permission gate should prompt you first

---

## Keeping up to date

```bash
git pull
pi update
```

If agent `.md` files changed, re-run the bootstrap script.

---

## Customizing

### Add a skill

Create `skills/<name>/SKILL.md` with YAML frontmatter:

```markdown
---
name: my-skill
description: One-line description the agent reads to decide if this skill is relevant.
---

## Instructions

Step-by-step methodology for the agent to follow.
```

The `description` field is critical: pi loads it at startup and uses it to decide when to activate the skill. Make it specific.

### Add a prompt template

Drop a `.md` file in `prompts/`. The filename (without `.md`) becomes the slash command.

```markdown
---
description: What this prompt does
---
Use the subagent tool to run the "worker" agent on: $@
```

Use `$@` to forward arguments typed after the slash command.

### Add a subagent

Create `agents/<name>.md` with YAML frontmatter:

```markdown
---
name: my-agent
description: One-line description of what this agent does
tools: read, grep, find, ls, bash
---

System prompt goes here.
```

Specifying `model` is optional. If omitted, the agent inherits the model active in your pi session.

Re-run the bootstrap script to install it.

### Add an extension

1. Create a `.ts` file in `extensions/`
2. Add its path to the `"extensions"` array in `package.json`
3. Run `pi update` to reload

```typescript
import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.registerCommand("hello", {
    description: "Say hello",
    handler: async (_args, ctx) => {
      ctx.ui.notify("Hello from my extension!");
    },
  });
}
```

---

## License

MIT