pi-extension

Pi Extension Development

Build Pi coding-agent extensions with the current ExtensionAPI. Use the Pi documentation and examples that come with your installed Pi package as the canonical source when in doubt. Typical locations are the package docs/, examples/extensions/, and generated type definitions for the installed version.

When implementing or debugging an extension, read the relevant docs/examples for your installed Pi version first and prefer current examples over memory.

Current API Quick Start

// ~/.pi/agent/extensions/my-extension.ts
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";

export default function (pi: ExtensionAPI) {
  pi.registerCommand("hello", {
    description: "Say hello",
    handler: async (args, ctx) => {
      // args is the raw string after /hello, not an object.
      ctx.ui.notify(`Hello ${args.trim() || "world"}!`, "info");
    },
  });

  pi.registerTool({
    name: "greet",
    label: "Greet",
    description: "Greet someone by name",
    parameters: Type.Object({ name: Type.String() }),
    async execute(toolCallId, params, signal, onUpdate, ctx) {
      return {
        content: [{ type: "text", text: `Hello ${params.name}!` }],
        details: {},
      };
    },
  });
}

Extension Locations

Auto-discovered extensions:

Location	Scope
~/.pi/agent/extensions/*.ts	Global top-level file
~/.pi/agent/extensions/*/index.ts	Global directory extension
.pi/extensions/*.ts	Project-local top-level file
.pi/extensions/*/index.ts	Project-local directory extension

Hot-reload auto-discovered extensions with /reload.

Current Command API

Commands are registered with handler, and the first parameter is always a string containing the raw command tail.

pi.registerCommand("goal", {
  description: "Start a goal",
  getArgumentCompletions: async (prefix) => [{ value: "status", label: "status" }],
  handler: async (args, ctx) => {
    const input = args.trim();
    if (!input) {
      ctx.ui.notify("Usage: /goal <objective>", "warning");
      return;
    }
    // ...
  },
});