Creating Pi Extensions

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:

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)