ExtensionAPI

API interface provided to extensions for interacting with the agent

The ExtensionAPI interface provides extensions with methods to interact with the agent, register tools and commands, and respond to events.

Import

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

Interface

Extensions receive the ExtensionAPI through the ExtensionContext when they are initialized.

export interface Extension {
  init(context: ExtensionContext): Promise<void> | void;
}

interface ExtensionContext {
  api: ExtensionAPI;
  actions: ExtensionActions;
}

Methods

registerTool

Register a custom tool that the agent can invoke.

registerTool(tool: ToolDefinition): void

tool · ToolDefinition · required

Show properties

name · string · required

Unique tool name

label · string · required

Display label for the tool

description · string · required

Description sent to the LLM

parameters · TSchema · required

TypeBox schema for tool parameters

execute · function · required

Function that executes the tool. Receives (toolCallId, args, signal?) and returns { content, details }

registerCommand

Register a slash command that users can invoke.

registerCommand(command: RegisteredCommand): void

command · RegisteredCommand · required

Show properties

name · string · required

Command name (without leading slash)

description · string · required

Description shown in autocomplete

shortcut · string

Keyboard shortcut (e.g., “ctrl+k”)

handler · function · required

Function that executes the command. Receives ExtensionCommandContext

on

Subscribe to extension events.

on<T extends ExtensionEvent>(type: T['type'], handler: ExtensionHandler<T>): void

type · string · required

Event type to subscribe to (e.g., “tool_call”, “session_start”)

handler · function · required

Event handler function

Available Events:

• agent_start / agent_end - Agent turn lifecycle
• tool_call / tool_result - Tool invocation
• session_start / session_shutdown - Session lifecycle
• session_compact / session_fork / session_switch - Session operations
• input - User input events
• turn_start / turn_end - Turn boundaries

exec

Execute a bash command.

exec(command: string, options?: ExecOptions): Promise<ExecResult>

command · string · required

The bash command to execute

options · ExecOptions

Show properties

cwd · string

Working directory for command execution

signal · AbortSignal

Abort signal for cancellation

ExecResult · object

Show properties

stdout · string

Standard output from the command

stderr · string

Standard error from the command

exitCode · number

Exit code (0 for success)

showDialog

Display a dialog to the user (TUI only).

showDialog(options: ExtensionUIDialogOptions): Promise<string | undefined>

options · ExtensionUIDialogOptions · required

Show properties

title · string · required

Dialog title

component · Component · required

TUI component to render

showWidget

Show a persistent widget in the footer (TUI only).

showWidget(options: ExtensionWidgetOptions): void

options · ExtensionWidgetOptions · required

Show properties

id · string · required

Unique widget ID

component · Component · required

TUI component to render

placement · 'left' | 'right'

Widget placement in footer. Default: 'right'

Example

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

export const myExtension: Extension = {
  async init(context: ExtensionContext) {
    const { api } = context;
    
    // Register a custom tool
    api.registerTool({
      name: "get_time",
      label: "Get Time",
      description: "Get the current time",
      parameters: Type.Object({}),
      execute: async () => {
        return {
          content: [{ type: "text", text: new Date().toISOString() }],
          details: {},
        };
      },
    });
    
    // Register a slash command
    api.registerCommand({
      name: "time",
      description: "Insert current time",
      shortcut: "ctrl+t",
      handler: async (ctx) => {
        const time = new Date().toISOString();
        await ctx.actions.sendMessage(time);
      },
    });
    
    // Subscribe to events
    api.on("tool_call", (event) => {
      console.log(`Tool called: ${event.toolName}`);
    });
  },
};

ExtensionActions

The ExtensionActions interface provides methods for modifying agent state.

sendMessage

Send a user message to the agent.

sendMessage(text: string): Promise<void>

setModel

Change the active model.

setModel(model: Model, thinkingLevel?: ThinkingLevel): void

setThinkingLevel

Change the thinking level.

setThinkingLevel(level: ThinkingLevel): void

setActiveTools

Set which tools are currently active.

setActiveTools(toolNames: string[]): void