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