Skill: Creating Pi Extensions
When to Use
- Creating new pi extensions with slash commands
- Building interactive overlay modals (pickers, editors, lists)
- Adding keyboard shortcuts to pi
- Understanding pi extension API patterns
Quick Start
import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
export default function myExtension(pi: ExtensionAPI) {
pi.registerCommand("mycommand", {
description: "Does something useful",
handler: async (args, ctx) => {
ctx.ui.notify("Hello from extension!", "info");
},
});
}Reference Documents
Read these in order based on your task:
| Document | Use When |
|---|---|
| File Structure | Starting a new extension |
| Code Patterns | Implementing extension logic |
| UX Patterns | Designing user interactions |
| TUI: Overlay Basics | Creating modal dialogs |
| TUI: Lists & Pickers | Building scrollable lists with search |
| TUI: Forms & Input | Text input and form fields |
| Inspiration | Real-world extension examples |
Key Imports
// Extension API types
import type { ExtensionAPI, ExtensionCommandContext, Theme } from "@mariozechner/pi-coding-agent";
// TUI utilities
import { matchesKey, visibleWidth } from "@mariozechner/pi-tui";
// Configuration (recommended)
import { createConfigService } from "pi-extension-config";Extension Entry Point
Extensions export a default function that receives the pi API:
export default function extensionName(pi: ExtensionAPI) {
// Register commands, shortcuts, etc.
}Checklist
Before submitting an extension:
- Commands have clear descriptions
- Keyboard shortcuts don't conflict with pi defaults
- Overlays handle Escape to cancel
- Error states show helpful messages via
ctx.ui.notify() - Theme colors used consistently (
accent,border,dim,muted,warning,error)