Documentation Index
Fetch the complete documentation index at: https://mintlify.com/badlogic/pi-mono/llms.txt
Use this file to discover all available pages before exploring further.
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
Register a custom tool that the agent can invoke.
registerTool(tool: ToolDefinition): void
Display label for the tool
Description sent to the LLM
TypeBox schema for tool parameters
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
Command name (without leading slash)
Description shown in autocomplete
Keyboard shortcut (e.g., “ctrl+k”)
Function that executes the command. Receives ExtensionCommandContext
on<T extends ExtensionEvent>(type: T['type'], handler: ExtensionHandler<T>): void
Event type to subscribe to (e.g., “tool_call”, “session_start”)
agent_start / agent_end - Agent turn lifecycletool_call / tool_result - Tool invocationsession_start / session_shutdown - Session lifecyclesession_compact / session_fork / session_switch - Session operationsinput - User input eventsturn_start / turn_end - Turn boundaries
exec
Execute a bash command.
exec(command: string, options?: ExecOptions): Promise<ExecResult>
The bash command to execute
Working directory for command execution
Abort signal for cancellation
Standard output from the command
Standard error from the command
Exit code (0 for success)
showDialog
Display a dialog to the user (TUI only).
showDialog(options: ExtensionUIDialogOptions): Promise<string | undefined>
options
ExtensionUIDialogOptions
required
showWidget(options: ExtensionWidgetOptions): void
options
ExtensionWidgetOptions
required
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(toolNames: string[]): void