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 )