pi Desktop

The desktop app for the pi coding agent — same agent you run in the terminal, now with a timeline, side panels, and a real window.

简体中文 · Getting started · Adapters

If you use pi in the terminal, you've probably wished for: a real diff view instead of scrolling raw output, the ability to queue a follow-up while the agent is still running, and a session tree you can click through instead of typing /tree. pi Desktop gives you all of that, plus native windows for extension pop-ups — without forking pi or touching your installed extensions.

• Streaming timeline — markdown, code blocks, KaTeX math, and foldable tool steps (read, edit, bash) with line-level diffs
• Session tree — branch and rewind like pi /tree, but clickable; with git, optionally restore files on jump
• Composer — inline file attachments, image paste, model & thinking-level pills, slash command menu; Files panel tree supports drag files into composer or right-click attach
• Workspace file preview — multi-tab (Ctrl/⌘+click or right-click Open in new tab), line-gutter source view, expand preview into the chat column for wide reading
• Queue messages — keep typing while the agent runs; messages execute when the current turn ends
• Full pi package ecosystem — every extension you installed for terminal pi works here: dialogs, tool cards, side panels, and /commands are translated to native UI by per-extension adapters, with no changes to the npm packages (see Extensions)
• Bilingual UI — 中文 / English toggle in Settings
• Voice input — optional mic → local transcription via codex-asr (bundled binary, ChatGPT/Codex token auth)
• Shared everything — sessions, auth, settings.json, extensions: all in ~/.pi/agent, shared with CLI pi

Windows — download the installer or portable build from Releases.

Build from source (developers):

git clone https://github.com/justhil/pi-app.git
cd pi-app
npm install
npm run dev

1. Open a folder — your repo becomes the agent's working directory (or use a sandbox under "chat partitions" to experiment safely).
2. Pick a session — old chats from terminal pi show up here; or start fresh with +.
3. Send a message — Enter to send, Shift+Enter for a new line.
4. Check the right panel — review, run, context, session tree, or Files (tabbed preview + explorer; expand preview across the chat column).
5. Jump back — hover a message and undo, or double-tap Esc with an empty input to open the session tree.

pi has a growing ecosystem of npm packages — subagents, image generation, search, hash-anchored edits, MCP servers, and more. pi Desktop makes all of them work on the desktop without forking pi or patching the packages.

Each extension ships a terminal TUI (select, confirm, surveys, tool cards, /commands). pi Desktop ships a compatibility layer plus per-extension adapters — small JSON descriptions that map that TUI onto native windows, timeline cards, and settings forms. You install and enable extensions exactly as you do for terminal pi; pi Desktop renders them.

1. Install in terminal pi: pi install npm:<name> or pi install git:github.com/...
2. Enable in ~/.pi/agent/settings.json → packages
3. Open Settings → Extensions in pi Desktop to confirm tools are loaded for the current session
4. If something's missing, start a fresh session after enabling the package

Extension pop-ups (questions, image approval, confirm dialogs) appear as native windows. Per-extension desktop options live under Settings → Desktop adapters. Advanced users can override builtin adapters with JSON in ~/.pi/desktop/adapters/.

Full list of 34 built-in desktop adapters: doc/guide/adapters.en.md · Author your own: adapter-authoring-guide.md

The composer mic records audio and transcribes it locally using codex-asr. It's optional — typing always works without it.

Open Settings → Voice:

• Provider — defaults to the bundled codex-asr serve binary (shipped in resources/codex-asr/); falls back to codex-asr on your PATH, or an external serve URL.
• Auth — paste a ChatGPT/Codex access_token, or click import from ~/.codex/auth.json (written by the Codex CLI or ChatGPT desktop after sign-in). Tokens are JWTs and expire — refresh by signing in again.
• Connectivity test — a one-click check reports whether the serve process started and the token is valid.

Bundled binaries come from codex-asr releases. If absent, the app falls back to any codex-asr found on your system PATH.

Questions and feedback: LinuxDo

If pi Desktop saves you from staring at a terminal all day, a star on GitHub helps others find it.