Build your first extension

An extension is a Pi module loaded by Salambo's authenticated extension host inside the sandbox. It can register tools, react to lifecycle events, run sandbox commands, and coordinate with other extensions without executing customer code in the trusted worker.

1. Create the module

Create .pi/extensions/support.ts:

import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';

export default function supportExtension(pi: ExtensionAPI) {
  pi.registerTool({
    name: 'format_case_reference',
    label: 'Format case reference',
    description: 'Format a customer support case identifier.',
    parameters: {
      type: 'object',
      properties: {
        caseId: {
          type: 'string',
          description: 'The customer support case identifier.',
        },
      },
      required: ['caseId'],
      additionalProperties: false,
    },
    async execute(_toolCallId, { caseId }) {
      return {
        content: [
          {
            type: 'text',
            text: `CASE-${caseId.trim().toUpperCase()}`,
          },
        ],
      };
    },
  });
}

The default export receives the hosted Pi 0.83 API. Depot transpiles the module and records its provenance. The extension factory executes only inside the sandbox sidecar.

Add the Pi package for local types:

pnpm add -D @earendil-works/pi-coding-agent@0.83

Salambo does not bundle this development dependency into your runtime artifact. Your project remains responsible for its normal TypeScript check.

2. Use Pi discovery

Pi discovers modules under .pi/extensions/. No duplicate extension declaration is required in salambo.yaml.

The hosted runtime activates discovered extension tools by default. An extension can change the active tool set through the supported Pi API.

3. Validate discovery

salambo manifest --path . --json

Inspect the compiled extension entry for:

• the normalized entrypoint;
• the tool name and description;
• the JSON parameter schema;
• the extension execution identifier.

manifest validates the hosted profile and build inputs. It does not run the extension factory, tools, or lifecycle handlers.

4. Deploy and execute it

salambo deploy
salambo smoke "Use format_case_reference for case 42 and return only the result."

Inspect the run's Activity and Diagnostics views to confirm the extension tool call and result.

Important boundary

Hosted compatibility covers the server-safe Pi surface. Interactive commands, shortcuts, flags, terminal renderers, editor controls, and session-tree navigation stay local to the Pi coding agent. See the exact compatibility profile.

Next, learn the complete custom tool contract and then react to lifecycle events.