An open-source desktop GUI for the pi coding agent.
Pi Desktop is a shell: the actual agent is pi itself, running in the
background as pi --mode rpc (JSONL over stdin/stdout). It reuses your
existing pi data in ~/.pi/agent — settings, models, auth, sessions,
extensions and skills — so chats you start in the app remain fully
compatible with the pi TUI (pi -r, pi --session) and vice versa.
- One window, all your pi chats — sessions are indexed, grouped by project and date, and shared with the pi TUI. The ⌘K palette searches titles and the text of every conversation (opening a hit lands on the match); ⌘⇧F filters the sidebar. Pin chats to the top or archive them. The home screen lists the chats that are working or waiting for you, then your most recent ones across every project. ⌃Tab cycles the open chats.
- Full chat engine — streaming replies, thinking blocks, markdown with syntax highlighting, agent work as a soft list of steps (shell steps as terminal cards with exit status, edits with line stats, consecutive calls folded into one row with diff stats, long runs folded into a "Worked for 2m 15s" summary), edits as unified diffs, retry and compaction notices (a compaction unfolds its summary), output tokens and cost per turn, stop / steer / follow-up controls with the queued messages shown above the composer, find in chat (⌘F), ⌥↑/⌥↓ to step through prompts, an image viewer, and a live "Working 0:42" timer in the title bar while pi works.
- Composer —
@mentions for project files,!commandto run a shell command in pi (its output joins the next prompt), image and file attachments (drag, paste or ⌘U), a draft kept per chat, ↑ to recall earlier prompts, a pixel context-usage gauge with session stats, and dictation (⌘⇧D; on-device where macOS supports the language). - Model & thinking-level picker — live catalog from pi
(
get_available_models), grouped by provider, with a thinking-effort slider that charges up at the model's top level. - Slash commands — pi's skills, prompt templates and extension
commands, plus app commands like
/new,/name,/compact,/fork,/tree,/export,/model,/thinkingand/hotkeys. - Session management — rename, export to HTML, copy as Markdown,
import a
.jsonl, reveal in Finder, copy path, move to Trash, fork from any user message, and clone a chat. - Project at a glance — the chat header shows the git branch and the working tree's changes (click for the diff) and opens the project in Finder, a terminal or an installed editor.
- Projects and chats — sessions nest under their project folder, and each project gets its own pixel sigil so it is recognizable in every list; project-less chats run in an app-owned scratch workspace.
- Side panel — browser tabs, a real terminal (
node-pty+ xterm), a live git diff view for the chat's project, its pull request and a read-only file viewer (open a file from any read / edit / write step or from the diff). ⌘⌥B toggles the panel, ⌃` a terminal, ⌘L the address bar. - Review and ship from the diff — comment on any diff line and hand the comments to pi as one prompt; "Review" has pi read the changes in a separate process, with the chat's model or any other one you pick (a second model checking the first one's work), and pin its remarks to the lines. Comments are kept per project on the computer, so the window and a paired phone show the same ones until you commit or hand them to pi, and "PR" posts them to the branch's pull request as one GitHub review signed pi-bot (from a bot account of yours if you set one in Settings); discard a file's changes (untracked files go to the Trash); commit everything and push without leaving the app.
- Checkpoints — in a git project the files are snapshotted before every prompt. Hover a prompt and restore the files to how they were before it; the restore itself can be undone. Nothing is committed or staged, and files created since go to the Trash.
- Side chat — ⌘; or
/btwasks a question with the chat's context in a side-panel tab. Nothing asked there is added to the chat. - Branches and worktrees — the branch chip in the chat header opens the
branch menu: switch the folder to a branch (a remote one gets a tracking
branch), create a branch, open any branch in a new worktree chat, or go to
one of the repository's worktrees (also ones made outside the app).
"New Chat in a Worktree" (project menu or ⌘K) gives a chat its own git
worktree on a fresh
pi/…branch, so several chats can change the same project in parallel without touching each other's files; removing a worktree can take its merged branch with it. - Automations — prompts pi runs on a schedule (daily at a time, weekdays only, or every N minutes/hours) while the app is open. Each run is an ordinary chat that starts in the background and notifies you when it is done; a run missed while the app was closed happens once when it opens.
- Pull requests — when the project's branch has a pull request, the chat
header shows its number and check state (via the GitHub CLI,
gh). The popover lists the checks, drafts a fix prompt with the failed job's log, and can hand failures to pi automatically while the chat is on screen. "Open in panel" (or the panel's new-tab page, or ⌘K) keeps the same view in a side-panel tab, where a failed job also unfolds the end of its log. - Usage — Settings → Usage shows the last 30 days of tokens and cost by day, model and project, read from the usage pi records in each session.
- Agent browser — pi can drive the in-app browser itself through an
extension that ships with the app:
browser_open,browser_click,browser_screenshotand friends, backed by Chrome DevTools Protocol. - Computer use — with Accessibility and Screen Recording granted, pi
can operate native macOS apps through
computer_*tools (accessibility tree, screenshots, clicks, typing). A strip above the composer shows what it is doing; pause or stop it anytime (⌃⌥⌘P). - Remote control — pair your phone with a QR code (Settings → Remote
control) and drive the app from Pi Remote, the companion app for Android
(
mobile/) and iOS (ios/): follow and steer chats, answer pi's questions, review and commit. The phone connects straight to your computer over your network, end-to-end encrypted, with no account or relay (how it works). On a server,pi-remotehosts the same link without the desktop app (pi-remote). - Images for you — pi's
show_imagetool puts an image file (a screenshot it saved, a chart it drew) in front of you in the chat, on the desktop and on the phone; screenshots stay visible under folded steps. - Notifications — a native notification and dock badge when a run finishes or pi needs your input while you are elsewhere.
- Runtime flexibility — uses your installed
pi, the bundled pinned@earendil-works/pi-coding-agent, or a custom path you choose in Settings. Spare pi processes are kept warm so new chats and reopened sessions skip pi's startup. - Easy on the battery — no looping animations: live indicators share
one 1 Hz clock, streaming renders at ~30 fps (10 fps while you are in
another app), and an idle window stays near 0% CPU
(
node scripts/energy.mjsmeasures it). - Its own look — content on sheets inset from the window, an IBM Plex
Mono instrument layer for times, tokens, models and tool calls, square
status pixels in the pi mark's colors, a pixel sigil per project, and
agent work shown as a trace on a rail (see
docs/design.md). - Native feel — dark/light themes following the system, native
menus and dialogs, keyboard shortcuts (⌘N new chat, ⌘B sidebar,
⌘[ / ⌘] history, ⌘, settings;
/hotkeyslists them all).
Grab the latest .dmg (or .zip) for Apple Silicon (arm64) or Intel
(x64) from Releases.
Builds are signed with a Developer ID and notarized by Apple, so they open
like any other app.
Computer use needs Accessibility and Screen Recording permission for Pi Desktop (System Settings → Privacy & Security); Settings → Computer use shows both and opens the right panes. Dictation asks for the microphone and speech recognition the first time you use it. Upgrading from 0.4.0 or earlier (unsigned builds): grant these once more, since macOS sees the signed app as new; later updates keep them.
Requirements: macOS 13+, Node.js 22.19+, pnpm and the
Xcode Command Line Tools (swiftc builds the native helpers).
git clone https://github.com/azygoss/pi-desktop.git
cd pi-desktop
pnpm install
pnpm dist:mac # release/*.dmg + *.zip (arm64 + x64)
# or for a quick unpacked build:
pnpm dist:dir # release/mac-*/Pi Desktop.appWithout a signing identity in your keychain the build is unsigned; macOS then asks you to confirm opening it (right-click → Open), and computer use cannot inherit the app's permissions.
pnpm dist:mac signs with the keychain's Developer ID Application
identity (or the one named in CSC_NAME) under the hardened runtime,
including the Swift helpers, so macOS attributes their Accessibility,
Screen Recording and microphone use to Pi Desktop. Notarization needs
credentials stored once in the keychain under a notarytool profile:
xcrun notarytool store-credentials pi-desktop-notary --team-id <TEAM_ID>It asks for your Apple ID and an app-specific password (create one at
account.apple.com → Sign-In and Security → App-Specific Passwords); an App
Store Connect API key works too (--key, --key-id, --issuer). Then:
pnpm dist:mac:release # sign + notarize + staple (profile: pi-desktop-notary)- pi is optional. When
piis not onPATH, Pi Desktop falls back to a bundled, pinned pi runtime (see Settings → Pi runtime to force a mode or point at a custom executable). - Authentication is handled by pi itself: run
pionce in a terminal and use/login, or configure API keys per the pi docs. Pi Desktop never touches credentials.
┌──────────────┐ typed IPC (contextBridge) ┌──────────────┐ JSONL ┌─────────────────┐
│ Renderer │◀───────────────────────────▶│ Main │◀───────▶│ Swift helpers │
│ React UI │ window.piDesktop.* │ Node host │ │ computer use, │
└──────────────┘ └──┬────────▲──┘ │ dictation │
│ │ └─────────────────┘
spawn per chat, │ │ browser_* / computer_* calls
JSONL over stdio ▼ │ (loopback HTTP, per-chat token)
┌───────────┴──┐
│ pi --mode rpc│
│ (the agent) │
└──────────────┘
The renderer is fully sandboxed (contextIsolation, sandbox, strict
CSP) and only talks to a minimal typed preload API. The main process owns
the pi child processes — one per open chat, plus warm spares — and
validates every IPC input. Pi Desktop never re-implements agent logic;
models, commands, sessions, skills and extension UI all come from the real
pi.
An extension that ships with the app registers the browser_* and
computer_* tools in each pi process; they call back into the app over a
loopback HTTP bridge authenticated with a per-chat token. Native work runs
in two small Swift helpers (resources/cua-helper,
resources/dictation-helper) that speak JSONL over stdio.
- The app never reads, parses or displays
auth.jsonor any model registry/credential file. - Session
.jsonlfiles are read locally, only to index and display your chats. - Apart from pages you open in the browser panel, Pi Desktop itself makes
one network request (and, only while remote control is on, it accepts
connections from the phones you paired): a daily check of this repository's latest GitHub
release (turn it off in Settings → General). In a git project it also
runs your own
gh(when installed) to read the branch's pull request. Everything else that leaves your machine is what the pi agent sends to its configured model providers — including screenshots and accessibility trees when it uses computer use. - Dictation uses Apple's on-device speech recognition when the language supports it, otherwise Apple's speech service.
- Deleting a chat moves the session file to the OS Trash, never
rm.
pnpm install
pnpm dev # run the app in development
pnpm typecheck # TypeScript checks (main + renderer)
pnpm lint # ESLint
pnpm test # Vitest unit tests
pnpm test:e2e # Electron e2e against a synthetic fake pi
pnpm build # production build
pnpm build:cua # compile the Swift computer-use + dictation helpers
pnpm dist:dir # unpacked .app (quick packaging check)
pnpm dist:mac # dmg + zip for macOS, signed when a Developer ID is in the keychain
pnpm dist:mac:release # dist:mac + notarize and staple
node scripts/energy.mjs # CPU + wakeups per phase: idle, streaming, tool run, panel
node scripts/perf.mjs # startup, session open, IPC throughput, frame timingBoth harnesses run the built app (pnpm build) against the synthetic fake
pi and never touch ~/.pi.
Environment overrides (tests and development):
| Variable | Effect |
|---|---|
PI_DESKTOP_PI_COMMAND |
Path to the pi executable (the e2e suite points it at test/fixtures/fake-pi.mjs) |
PI_DESKTOP_USER_DATA_DIR |
App data directory instead of Electron's userData |
PI_CODING_AGENT_DIR / PI_CODING_AGENT_SESSION_DIR |
pi's agent / sessions directory |
PI_DESKTOP_CUA_HELPER / PI_DESKTOP_DICTATION_HELPER |
Custom helper binaries |
PI_DESKTOP_GH_COMMAND |
Stand-in for the GitHub CLI (the e2e suite uses test/fixtures/fake-gh.mjs) |
PI_DESKTOP_PERF=1 |
React commit counters read by scripts/perf.mjs |
See CONTRIBUTING.md and the agent-facing rules in AGENTS.md. Bug reports are welcome — please don't paste API keys or session contents into issues.
pi is built by Earendil / Mario Zechner. Pi Desktop is a community project and is not affiliated with or endorsed by pi. The pi logo used in the app icon and UI (build/pi-logo.svg, downloaded from pi.dev) belongs to Earendil / the pi project and is used solely to identify pi.
MIT — Copyright © 2026 Pi Desktop contributors.


