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.

Install

Install Pi from its official npm package:

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

On macOS or Linux, the official installer is also available:

curl -fsSL https://pi.dev/install.sh | sh

Verify the executable:

pi --version

Authenticate

Start Pi in a normal terminal:

pi

For supported subscription providers, use:

/login

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
pi

Confirm 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.

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 Pi and its unpinned packages from Pi itself:

pi update

To update only the CLI:

pi update --self

You can also update the global npm package through the package manager that installed it. Restart Synara after changing the runtime.

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, and the bundled Pi SDK recognizes GLM 5.3 Flash and GPT-6 Astra. Availability still depends on the 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 --version from 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.

Pi