Pi Desktop

A native desktop home for Pi Agent.
Your Pi configuration. Your models. A workspace of your own.

Install · Run locally · Development guide · Issues

Early preview — chat runs through your installed Pi CLI. New local threads execute through pi --mode rpc: streaming answers, thinking, tool calls, approvals, cancellation, Pi session history, session tree navigation and Pi's slash commands. This is an independent desktop project, currently being migrated from Cline; parts of the tree are still inherited Cline code.

What works today

• A native window. Tauri 2 wraps a Next.js interface and a Bun backend. The app opens as Pi, not a browser tab.
• Chat through Pi. Each active thread is a pi --mode rpc process started from the thread's workspace with the picked provider, model and thinking level. Assistant text and thinking stream live; bash, read, edit, write, grep and extension tools show as tool cards with live output; token usage and cost come from Pi.
• Tool approvals, opt-in. Tools run without asking by default, like the Pi CLI. Flip the composer's shield to Ask first and every tool call waits for your approval; the switch works mid-session.
• Extension dialogs. When an installed Pi extension asks a question (select, input, confirm, editor), it appears as a question card in the chat; notifications land in the transcript log.
• Stop, queue, steer. Stop a running turn. Messages sent while Pi is busy wait in a queue, images included, and go out one by one when Pi finishes; edit, remove, or steer any of them into the running turn. Stopping your own turn lets the queue continue; stopping a queued turn clears the rest.
• Pi session history. Sessions from ~/.pi/agent/sessions appear in the sidebar with the Pi source label. Open one to read it, continue it (Pi is relaunched on that session file), rename or delete it; the same sessions show up in pi /resume.
• Pi's slash commands. Typing / lists the extension commands, prompt templates and skills your installed Pi offers for that workspace. Builtins run in the app where they can: /compact, /name, /session, /copy, /export (HTML), /model <model> and /thinking <level>; /new, /model, /thinking, /settings and /resume open the matching desktop controls. Installing or removing Pi packages in a terminal refreshes the list and the model picker automatically.
• Edit and fork. Edit one of your earlier messages to fork the session from just before it: a new Pi session opens with your edited text in the composer, and the original stays as it was. Fork copies the whole session.
• Session tree. /tree shows the thread's whole Pi session tree and switches branches without a model turn. Picking an earlier message of yours rewinds to just before it and puts its text back in the composer, so sending starts a new branch (images from that message are not restored).
• Model cycling. On a live thread, Ctrl+P cycles through Pi's scoped models. /scoped-models chooses which models are in that cycle, either for the current session or saved to Pi's enabledModels.
• Pi extensions in Settings. Extensions → Installed lists the extensions your global and project Pi configuration resolve. Enable or disable each one, or uninstall an npm/git package after confirmation (local extension files can only be disabled). Browsing links to pi.dev/packages; the app never installs or updates packages.
• Your configured Pi models. Browse providers and models from your local Pi configuration, filtered by enabledModels with Pi's own resolver, rather than an unfiltered built-in catalog.
• Selections that stay with you. Each provider remembers its model; each provider/model pair remembers its thinking level. Pi startup defaults seed the picker when no desktop selection is saved.
• Model-aware thinking controls. Available levels come from model capabilities. Unknown extension capabilities are not guessed.
• Light and dark themes. Saved preferences and system appearance are respected, with a coral accent and the Pi mark throughout the app.
• A local-first entry screen. Choose a workspace and see its branch without Cline onboarding or an account sign-in. Cline Cloud is disabled.

Not yet: file checkpoints for Pi threads, and SSH remote threads (those still run on the inherited Cline runtime). The Automations sidebar entry is an inherited UI surface, not a Pi feature.

Install (macOS beta)

Grab the latest Pi_<version>_aarch64-local-unsigned.dmg from Releases and drag Pi to Applications. You need the pi CLI installed and configured; the app drives it, it does not bundle it.

The beta is ad-hoc signed and not notarized, so macOS blocks the first launch. Either open System Settings → Privacy & Security and choose Open Anyway, or run:

xattr -dr com.apple.quarantine "/Applications/Pi.app"

The release also carries test installers for Intel Macs, Windows (NSIS) and Linux (DEB/RPM; on Linux the app and package are named Pi Desktop / pi-desktop). They are unsigned and have only been verified to package, not to run. There is no auto-update: install newer betas by downloading them.

Run locally

Requirements

• Bun 1.3.13 and Node.js 22 or newer. Use Bun for dependency installation and scripts.
• A current stable Rust toolchain. The dependency graph requires Rust 1.85 or newer; the complete minimum-version matrix has not been verified.
• The Tauri platform prerequisites, including Xcode Command Line Tools on macOS.
• An installed pi CLI on your PATH (or PI_DESKTOP_PI_BIN pointing at it) with a configured ~/.pi/agent. Pi runs the chat; the desktop only drives it.

cd ~/Desktop
git clone https://github.com/KayanoLiam/pi-desktop.git
cd pi-desktop

bun install --frozen-lockfile
bun run build:sdk

cd apps/examples/desktop-app
bun run dev

This launches the native Tauri app. Its development webview uses port 3125; the sidecar uses 3126. Stop conflicting desktop/headless development processes first. The first launch builds native dependencies, the sidecar, and SSH helpers, and may download build tools.

For browser-only debugging, use bun run dev:headless from the app directory. It does not open a native window. An older installed Cline app does not reflect this checkout.

macOS on Apple Silicon is the currently exercised native platform. The manual pi-desktop-package GitHub workflow packages unsigned test installers for macOS (Apple Silicon and Intel, ad-hoc signed), Windows (NSIS) and Linux (DEB/RPM) as workflow artifacts. It only checks that each installer is produced (and that the deb is named pi-desktop, since Ubuntu already has an unrelated pi package), so the Intel, Windows and Linux builds are untested beyond packaging. Signing, notarization, updates, and release automation still need migration.

Bring your Pi configuration

The catalog reads ~/.pi/agent, or the directory selected by PI_CODING_AGENT_DIR:

File	Used for
auth.json	Locally configured provider credentials and availability
models.json	Custom providers and models
models-store.json	Cached provider model metadata
settings.json	enabledModels, startup defaults, thinking preferences, and the packages and extensions shown in Extensions → Installed

Configure providers in Pi, then use the picker’s refresh control to reload. Model identity always includes both provider ID and model ID, so identical model names from different providers do not share a selection. A listed credential does not prove that a future model request will succeed.

How execution works, and what runs your code

Every active thread is a real pi --mode rpc process (the user's installed Pi, not a bundled copy), started in the thread's workspace with --session-id/--session, --model provider/id, --thinking level and one extra extension. It loads your Pi extensions, packages, credentials and settings, exactly like the terminal. That means:

• Extension code, tools and MCP servers configured in Pi run with your user's full permissions. Nothing here is a sandbox.
• RPC mode never shows Pi's project-trust prompt; project-local .pi resources follow Pi's saved trust decisions and defaultProjectTrust. The desktop does not pass --approve.
• The extra extension is a generated tool-approval gate written to ~/.cline/data/pi-desktop/extensions/. It hooks tool_call and asks the desktop before each tool runs; with auto-approve on (the default) the desktop answers yes immediately.
• Idle Pi processes exit after ten minutes and are relaunched on the thread's session file when you send again.

The model picker's catalog path is read-only (no credential refresh, no config writes, no API-key commands, no inference). Providers registered by installed Pi extensions are discovered by launching pi in RPC mode with PI_OFFLINE=1, no session and no tools; if Pi is unavailable, exact authenticated references stay visible with unknown thinking capabilities and nothing is invented.

Two desktop actions do change your Pi configuration, and only when you ask: Save to Pi settings in /scoped-models writes enabledModels, and Extensions → Installed writes enable/disable overrides or removes a package from your global or project Pi settings.

Architecture and migration

Tauri native shell
        │
Next.js / React webview
        │  local transport
Bun sidecar
        ├── Pi threads: one `pi --mode rpc` process per active session
        ├── Pi session files (~/.pi/agent/sessions) for history
        ├── Pi configuration: model catalog, scoped models, installed extensions
        └── Inherited Cline runtime (existing Cline sessions, SSH environments)

The goal is a standalone Pi desktop app. This checkout is not standalone yet: it retains the Cline monorepo and directly depends on @cline/core, @cline/llms, @cline/shared, and @cline/ui. Copying only the desktop directory will not produce a buildable project.

Path	Purpose
apps/examples/desktop-app/	Native app, webview, sidecar, and desktop development guide
sdk/packages/	Shared workspace dependencies still required by the desktop
docs/images/	Screenshots used by this README
Other apps/ directories	Retained upstream projects; not the focus of Pi Desktop

Existing Cline sessions and SSH environments retain their legacy execution paths. Removing Cline account screens does not remove those runtime dependencies. Bundle identifiers are Pi's own (io.github.kayanoliam.pi-desktop) and the updater endpoints are empty, so builds never check Cline's update feed; the updater signing key and the release workflow are still Cline's and must be replaced before an independent, auto-updating release.

Next milestones

• SSH remote threads and file checkpoints through Pi.
• Replace or extract the remaining Cline workspace/runtime dependencies.
• Migrate updates, signing, notarization, and release automation.
• Resolve inherited test/type/lint failures and establish desktop test CI (today only the manual packaging workflow exists).

Development

See the desktop development guide for commands, verification notes, native assets, and inherited runtime details. After SDK changes, rebuild with bun run build:sdk before testing or restarting the desktop: workspace packages resolve compiled dist/ output.

The current baseline is not all green. A successful web build is not a passing webview typecheck, and inherited GitHub workflows are not evidence of Pi Desktop compatibility. Please include exact commands and results when reporting a bug or contributing a change.

Acknowledgments and license

Pi Desktop builds on the Cline desktop architecture and the Pi coding-agent packages. Existing upstream code and copyright notices are retained.

This repository is licensed under Apache 2.0. Original Cline code © 2026 Cline Bot Inc. Dependencies remain under their respective licenses.