pi-agent-config

Personal pi 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 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 | | protected-paths | Safety | Blocks reads and writes to sensitive paths (.env, .git/, node_modules/) | badlogic/pi-mono | | confirm-destructive | Safety | Asks for confirmation before clearing or switching sessions | badlogic/pi-mono | | dirty-repo-guard | Safety | Warns when the repo has uncommitted changes before an agent run | badlogic/pi-mono | | questionnaire | Workflow | Lets the agent ask structured clarifying questions with a tab-based UI | badlogic/pi-mono | | git-checkpoint | Workflow | Creates a git stash checkpoint before each turn so /fork can restore the code state | 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 | | subagent | Workflow | Delegates tasks to specialized agents in isolated context windows (single / parallel / chain modes) | 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 | /commit command: generates a Conventional Commits message from staged diff, shows a confirmation UI, and commits | 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 | | debug | Systematic debugging: reproduce, isolate, hypothesize, verify, fix | s1lver091 | | refactor | Safe refactoring methodology: understand first, small steps, behavior preserved | s1lver091 | | plan | Pre-implementation planning: explore codebase, identify approach, produce actionable steps | s1lver091 | | spec | Technical specification writing: goals, data model, API design, edge cases, security | s1lver091 | | test | Test writing methodology: identify cases, write meaningful assertions, verify coverage | 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 | | planner | Converts scout output and requirements into a concrete, numbered implementation plan | s1lver091 | | worker | Autonomous implementation agent with full tool access | s1lver091 | | reviewer | Senior code reviewer focused on correctness, security, and maintainability (read-only) | 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 | | /scout-and-plan <task> | scout > planner: explore and produce a plan without touching any files | s1lver091 | | /implement-and-review <task> | worker > reviewer > worker: implement, code review, apply feedback | s1lver091 | | /fix <bug> | scout > worker: fast bug fix, skips planning for speed | s1lver091 | | /review [scope] | reviewer: standalone code review on the current git diff | 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 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:

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

2. Run the bootstrap

macOS / Linux:

bash scripts/bootstrap.sh

Windows (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:

pi install npm:pi-agent-config
pi install npm:pi-commit-message

Or from git:

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

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:

---
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.

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

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

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