Building TypeScript Extensions

Learn how to extend Pi with custom tools, event handlers, and UI components using TypeScript

Extensions are TypeScript modules that extend Pi’s behavior. They can register custom tools, subscribe to lifecycle events, add commands, and create custom UI components.

What You Can Build

Extensions enable:

• Custom tools - Register tools the LLM can call via pi.registerTool()
• Event interception - Block or modify tool calls, inject context, customize compaction
• User interaction - Prompt users via ctx.ui (select, confirm, input, notify)
• Custom UI components - Full TUI components with keyboard input
• Custom commands - Register commands like /mycommand
• Session persistence - Store state that survives restarts
• Custom rendering - Control how tool calls/results and messages appear

Quick Start

Create ~/.pi/agent/extensions/my-extension.ts:

import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
import { Type } from "@sinclair/typebox";

export default function (pi: ExtensionAPI) {
  // React to events
  pi.on("session_start", async (_event, ctx) => {
    ctx.ui.notify("Extension loaded!", "info");
  });

  pi.on("tool_call", async (event, ctx) => {
    if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
      const ok = await ctx.ui.confirm("Dangerous!", "Allow rm -rf?");
      if (!ok) return { block: true, reason: "Blocked by user" };
    }
  });

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

  // Register a command
  pi.registerCommand("hello", {
    description: "Say hello",
    handler: async (args, ctx) => {
      ctx.ui.notify(`Hello ${args || "world"}!`, "info");
    },
  });
}

Test with:

pi -e ./my-extension.ts

Extension Structure

Building a Custom Tool

Complete Tool Example

Here’s a complete working example:

import { Type } from "@sinclair/typebox";
import { Text } from "@mariozechner/pi-tui";
import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.registerTool({
    name: "hello",
    label: "Hello",
    description: "A simple greeting tool",
    parameters: Type.Object({
      name: Type.String({ description: "Name to greet" }),
    }),

    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
      const { name } = params as { name: string };
      return {
        content: [{ type: "text", text: `Hello, ${name}!` }],
        details: { greeted: name },
      };
    },

    renderCall(args, theme) {
      return new Text(
        theme.fg("toolTitle", theme.bold("hello ")) +
        theme.fg("muted", args.name),
        0, 0
      );
    },

    renderResult(result, options, theme) {
      return new Text(
        theme.fg("success", result.content[0].text),
        0, 0
      );
    },
  });
}

Event Handling

Subscribe to lifecycle events:

Session Events

pi.on("session_start", async (_event, ctx) => {
  // Session started
});

pi.on("session_shutdown", async (_event, ctx) => {
  // Clean up resources
});

Tool Events

import { isToolCallEventType } from "@mariozechner/pi-coding-agent";

pi.on("tool_call", async (event, ctx) => {
  if (isToolCallEventType("bash", event)) {
    // event.input is typed as { command: string }
    if (event.input.command.includes("rm -rf")) {
      return { block: true, reason: "Dangerous" };
    }
  }
});

pi.on("tool_result", async (event, ctx) => {
  // Modify tool results
  return { content: [...], details: {...} };
});

Message Events

pi.on("message_update", async (event, ctx) => {
  if (event.assistantMessageEvent.type === "text_delta") {
    // Process streaming text
  }
});

pi.on("before_agent_start", async (event, ctx) => {
  return {
    message: {
      customType: "my-extension",
      content: "Additional context",
      display: true,
    },
  };
});

State Management

Store state in tool result details for proper branching support:

export default function (pi: ExtensionAPI) {
  let items: string[] = [];

  // Reconstruct state from session
  pi.on("session_start", async (_event, ctx) => {
    items = [];
    for (const entry of ctx.sessionManager.getBranch()) {
      if (entry.type === "message" && entry.message.role === "toolResult") {
        if (entry.message.toolName === "my_tool") {
          items = entry.message.details?.items ?? [];
        }
      }
    }
  });

  pi.registerTool({
    name: "my_tool",
    // ...
    async execute(toolCallId, params, signal, onUpdate, ctx) {
      items.push("new item");
      return {
        content: [{ type: "text", text: "Added" }],
        details: { items: [...items] },  // Store for reconstruction
      };
    },
  });
}

User Interaction

Prompt users with dialogs:

Confirmation

const ok = await ctx.ui.confirm("Delete?", "This cannot be undone");
if (!ok) return;

Selection

const choice = await ctx.ui.select("Pick one:", ["A", "B", "C"]);

Input

const name = await ctx.ui.input("Name:", "placeholder");

Editor

const text = await ctx.ui.editor("Edit:", "prefilled text");

Notification

ctx.ui.notify("Done!", "info");  // "info" | "warning" | "error"

Available Imports

import type {
  ExtensionAPI,
  ExtensionContext,
  // Event types
  AgentSessionEvent,
  ToolCallEvent,
  // Tool types
  ToolDefinition,
  ToolInfo,
} from "@mariozechner/pi-coding-agent";

import { Type } from "@sinclair/typebox";
import { StringEnum } from "@mariozechner/pi-ai";
import { Text, Container, SelectList } from "@mariozechner/pi-tui";

Next Steps

• See Creating Skills for specialized task workflows
• See Custom Providers for adding LLM providers
• Check packages/coding-agent/examples/extensions/ for more examples