Docs/Providers

Pi

Moonfold can use your existing Pi coding agent installation while keeping Pi's models, auth, extensions, skills, context files, and native session history.

Set Up Pi

1. Install Pi on the machine running the Moonfold server. Pi requires Node.js 22.19 or newer; its platform installers can install Node if needed. Moonfold supports Pi 0.80.5 or newer.
2. Run pi in a terminal, then /login to connect your model provider or configure its API key.
3. Open Moonfold Settings, enable Pi, and refresh the provider.

For an npm installation, use:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

If pi is not on the server's PATH, set Pi's binary path to the executable. Provider environment variables and launch arguments are also available for installations that need a custom agent directory, endpoint, or model configuration. --provider must be paired with --model. Moonfold rejects launch arguments that change Pi's execution mode or select a session because Moonfold owns those parts of the process lifecycle.

On a remote or headless server, connect to that machine over SSH and run pi, then /login. Open the authorization URL on your own computer. If the callback cannot reach the server, paste the final redirect URL or authorization code back into Pi when prompted. You can also set your model provider's API-key environment variable in the Pi instance's settings; mark secret values as sensitive.

Update installer-managed Pi with pi update. If another package manager owns the installation, update it through that manager instead. For example, a Nix profile installation uses nix profile upgrade pi.

What Carries Over

Moonfold discovers the models reported by Pi and exposes their supported thinking levels. The thinking picker marks the discovered active model's configured level as its default without overriding it. Other models keep their Pi defaults when no level is selected. Threads use Pi's native session files for resume, rollback, and forks within the same Pi instance. Forks preserve the native conversation through the selected turn in the destination workspace. Switching providers uses portable conversation context. Extension dialogs appear in the Moonfold composer, and the composer context meter follows Pi's own usage reporting while a response streams and after it settles.

Pi skills appear in the composer's $ menu. This includes user skills and project skills that Pi loads for the current workspace; selecting one uses Pi's native skill expansion.

Pi loads its normal user and project extensions. Blocking select, confirm, input, and editor dialogs work in Moonfold. Notifications appear in the work log. Pi terminal decoration such as titles, status lines, and widgets does not have a Moonfold equivalent.

Permission Modes

Moonfold applies the composer permission mode through Pi's blocking tool hook:

• Supervised asks before commands, file changes, and extension tools. Read-only tools continue.
• Auto-accept edits allows Pi's edit and write tools, but asks before commands and extension tools.
• Full access allows tools without Moonfold approval prompts.

The Auto option is not shown for Pi because Pi does not expose an AI approval reviewer. Threads that already stored Auto before Pi support was added behave and display as Supervised.

Changing the mode restarts the Pi provider session and resumes the same native conversation. The policy covers Pi tool calls; it is not an operating-system sandbox, and code that a trusted Pi extension runs outside a tool call remains governed by Pi's own extension trust model.

Moonfold's delegate_task tool creates durable child threads in the shared subagent UI. If the user installs Pi's example subagent extension, Moonfold also shows its task progress and results in that UI. Pi runs those children without a session, so they cannot be opened or resumed as Moonfold threads.

Troubleshooting

• If Pi is unavailable, confirm that the configured binary runs on the server machine, then refresh the provider in Settings.
• If no models appear, open Pi directly and confirm its authentication and model configuration.
• If discovery cannot complete, Moonfold keeps Pi available with the Pi default model. Start a thread to let the interactive Pi session handle any startup prompt.
• If a project extension is missing, approve the project in Pi, then start a fresh provider session.
• If a project skill is missing from the $ menu, approve the project in Pi and refresh the provider.
• The context meter appears once Pi reports usage for the thread. Some model providers only report usage when a response completes, so the meter can wait for the first reply.

Edit this page on GitHub