Pi
Install, authenticate, verify, and run the Pi coding agent through Synara.
Synara integrates the Pi coding-agent runtime and its model registry. Pi owns provider credentials, models, extensions, skills, commands, and session behavior; Synara supplies the durable task, working environment, transcript, review surfaces, Agent Gateway connection, and Git lifecycle around it.
Pi is optional. Synara loads the SDK from the Pi CLI you select in provider settings or the pi executable it finds on the server's PATH. Use a Pi installation you trust because its SDK runs inside the Synara server. Extensions must be compatible with that installation's Pi version.
Install
Install Pi from its official npm package:
npm install -g --ignore-scripts @earendil-works/pi-coding-agentOn macOS or Linux, the official installer is also available:
curl -fsSL https://pi.dev/install.sh | shVerify the executable:
pi --versionAuthenticate
Start Pi in a normal terminal:
piFor supported subscription providers, use:
/loginFor the current ChatGPT subscription login, use /login openai. Those models appear under openai/ in Synara. The older openai-codex login is separate; do not rename or copy its credential into the openai entry.
Pi can also use provider API keys from environment variables or its credential store. For example, an Anthropic key can be supplied before launch:
export ANTHROPIC_API_KEY="..."Do not commit credentials or paste them into Synara tasks. Pi normally stores its user state under ~/.pi/agent/.
Verify
From a disposable repository:
pi --version
piConfirm that /login or the configured API-key provider makes at least one model available. Use /model to inspect the catalog, then ask Pi to summarize the repository without making changes.
This verifies the package, provider credentials, model registry, and working directory before Synara is involved.
Connect to Synara
Enable Pi
Open provider settings and confirm that Synara detects pi. If you have more than one installation, select the executable for the account you want to use.
Confirm provider credentials
Use Pi’s own /login, environment variables, or supported auth file. Synara reads the resulting model availability rather than duplicating the secret.
Refresh models and thinking levels
Confirm that the model picker shows the expected provider/model combinations and the thinking levels supported by the selected model.
In Synara 0.8.1 and later, the Anthropic catalog repair keeps Claude Fable 5.1 selectable even when Pi's authenticated upstream catalog predates that model entry. Fable 5.1 uses always-on thinking with Low through Max effort and no fast-mode lane.
Run a bounded task
Start with Pi’s built-in tools and a clean test repository before adding project extensions, skills, or packages that can execute code.
Capabilities in Synara
Pi sessions can expose:
- Pi’s available provider and model registry
- Thinking levels supported by the selected model
- Built-in read, write, edit, and shell tooling
- Commands, skills, attachments, and project instructions
- Session history and continuation behavior
- Tool output, task progress, usage, and context information
- User-input requests surfaced in the Synara conversation
- Native steering of a running turn
- Synara’s terminal, browser, diff, checkpoint, worktree, and Git delivery surfaces
A normal message sent during an active Pi turn is queued as a follow-up instead of failing with a streaming error. Explicit steering remains a separate request to incorporate a correction into the active turn; the runtime decides when it can act on it.
Pi automatic retries appear as inline warnings while the task remains active. End task also stops retry backoff and queued continuation. Extension status messages stay separate from tool activity.
Pi extensions and packages execute with the permissions of your user account. Review third-party code before enabling it in a repository Synara will operate.
Updating
Update the Pi installation selected in Synara, then fully quit and reopen Synara before refreshing Pi models.
Update the standalone Pi CLI and its unpinned packages from Pi itself:
pi updateTo update only the CLI:
pi update --selfYou can also update the global npm package through the package manager that installed it.
Pi 1.0.3 renamed the Azure provider to azure. Synara keeps azure-openai-responses as a runtime alias so existing Pi credentials, models.json overrides, and saved model selections continue using their original key. New azure profiles keep their own credentials. Synara does not rewrite either profile; moving a profile to the new ID is optional and follows the upstream migration instructions. Azure remains unavailable for isolated Pi accounts because its SDK routing can read process-level configuration.
Pi 1.3 moved Kimi Code to Chat Completions. Synara routes the old official https://api.kimi.com/coding endpoint to /coding/v1 when using that protocol, keeping existing credentials, model selections, and config files intact. Custom endpoints and explicit Anthropic protocol definitions keep their configured routing.
Model catalog refresh
Pi discovery uses its native OpenRouter authentication to expose models it can execute. OpenCode Zen entries are refreshed with their protocol and capability metadata. Available models depend on the installed Pi version, configured provider and account.
Discovery shares cached results and bounds retries. The currently selected provider takes priority over background prefetch; a discovery failure remains visible rather than being treated as proof that a static fallback is current.
Troubleshooting
Pi is not detected
- Run
pi --versionfrom a fresh terminal. - Confirm the global package-manager binary directory is on
PATH. - Check the custom binary path in Synara.
- Restart Synara after installation or shell changes.
No models are available
Run Pi directly and use /login, or configure a supported provider API key. Confirm /model shows at least one authenticated model before refreshing Synara.
If Anthropic authentication works but Fable 5.1 is missing, refresh Pi in Synara and start a new task. Synara can repair the known Anthropic catalog entry, but it cannot grant model access that the configured account or provider rejects.
ChatGPT models appear in Pi but not in Synara
Confirm both applications use the same Pi executable and agent directory. Restart Synara if you updated that installation, then refresh Pi models and look for openai/ after /login openai or openai-codex/ for the legacy login.
If Pi itself reports an expired or invalid login, authenticate again in that same profile and refresh Synara. A working current login does not need to be deleted or repeated just to upgrade Synara.
The model catalog differs between projects
Check Pi’s global and project settings, credentials, custom model definitions, and extensions. Project-level resources can change the provider catalog or behavior.
A third-party Pi package behaves unexpectedly
Disable the package and reproduce with Pi’s built-in runtime. Extensions run arbitrary code and can modify tools, commands, events, and provider behavior.
Official documentation
Continue with Your first task or Provider handoffs.
Source evidence: Synara v1.6.0 apps/server/src/provider/piSdkImports.ts, apps/server/src/provider/Layers/ProviderHealth.ts, and apps/server/src/provider/Layers/PiAdapter.ts.