Pi extensions

Use Pi extension APIs for agent tools and hooks, and understand OpenWaggle's desktop integration boundaries.

Use a Pi extension when you need to add an agent tool, register a provider, or respond to agent-session events. Pi is the coding-agent runtime inside OpenWaggle. A Pi extension changes runtime behavior; it does not automatically add desktop UI.

Start with Pi’s extension reference. If you also need a settings page, panel, or custom tool display, use the OpenWaggle extension package format to declare those desktop contributions.

Skills vs runtime extensions

A skill provides instructions. A runtime extension executes code and can change the tools available to the agent. Do not install runtime code merely to provide a repeatable prompt.

OpenWaggle supplies project resource roots to Pi in this order:

.openwaggle > .pi > .agents

OpenWaggle supplies roots for skills, extensions, prompts, and themes in that order. Enabled OpenWaggle packages can insert declared Pi resource roots before .pi. The managed .openwaggle/extensions package directory is not blindly loaded as executable Pi code: package eligibility controls which packages and declared roots reach Pi. Pi applies its own loading and conflict rules to the supplied resources. OpenWaggle packages have their own manifest and trust lifecycle; use Install extensions for that workflow.

Commands a Pi extension registers, and Pi’s own /mcp, are listed under Pi extensions when you type / in the composer, in a session or in a new session for a project.

Pi terminal UI renderers do not run as desktop UI. Standard interactions have OpenWaggle fallbacks, while custom interactions need a matching desktop renderer. See Interaction primitives.

For custom provider registration, see Pi’s pi.registerProvider() reference.

Integrating with the app

When changing OpenWaggle itself, keep Pi SDK imports in src/main/adapters/pi/. Application and IPC layers call OpenWaggle-owned ports; the renderer receives OpenWaggle-owned data and events. Dedicated packages/pi-* packages may use Pi SDKs within their package boundaries.

New tools should use Pi extension APIs rather than a second tool execution system. Desktop presentation and any new host capabilities need explicit support in OpenWaggle’s public contracts.

MCP

You do not need a Pi extension to connect an MCP server. Configure it through MCP settings.

OpenWaggle loads Pi’s built-in MCP, codemode, and tool-search extensions into every session, so MCP works as it does in the pi command. An extension that registers its own /mcp command, such as pi-mcp-adapter, replaces Pi’s built-in MCP in Pi; OpenWaggle does not load pi-mcp-adapter, because the built-in support already covers it.

In the same way, OpenWaggle does not load an installed @openwaggle/pi-waggle package, because OpenWaggle provides Waggle itself; the pi command still loads it.

Extensions can still add servers for a session with pi.registerMcpServer(), as in Pi.

For app development, keep transports, configuration files, and sign-in storage in src/main/adapters/mcp/, and the code that loads Pi’s extensions in src/main/adapters/pi/.