Skip to main content
Pi extensions plug into the agent execution engine that powers Aether. They add custom tools the agent can call during a turn, slash commands users can invoke directly, and session lifecycle hooks — all running inside the Pi framework’s agent loop.

​
What are Pi extensions?

Aether runs on the Pi agent framework (@earendil-works/pi-agent-core, @earendil-works/pi-coding-agent). Pi extensions are standard Pi framework extensions that gain full access to the agent loop running inside Aether. Because they execute in the Node.js bridge process, they have access to the full Node.js runtime and the Pi framework’s tool-calling and command dispatch infrastructure.

​
Declaring a Pi extension

Add a pi.extensions array to your package.json pointing at one or more entry files:
package.json
Each entry file is loaded by the Pi framework when the extension is activated.

​
The Pi extension factory

The entry file must export a default function that the Pi framework calls with an ExtensionAPI instance:
agent.ts
The factory may be synchronous or async. Use the pi parameter to register everything your extension provides.

​
Pi vs Aether extensions

A single package can contain both a Pi extension and an Aether Script Mod. They serve different roles: When you need both agent-loop capabilities and Android UI customisation in one package, keep the Pi factory as the default export and export the Aether factory as activateAether. See Tools & Commands for a combined example.
The Pi framework API (ExtensionAPI) is defined by the @earendil-works/pi-coding-agent package. Refer to the Pi framework documentation for the full API surface including session hooks, streaming, and advanced tool options.