Pi App AI Agent

<div align="center"> <img src="resources/icon.svg" alt="pi Desktop" width="72" height="72" />

pi Desktop

A desktop app for the pi coding agent.<br/> The same agent and the same ~/.pi/agent you use in the terminal — with a timeline, Git review, a built-in terminal, and an Android app to keep going from your phone.

English · 简体中文 · Download · Getting started · Adapters

</div> <picture> <source media="(prefers-color-scheme: dark)" srcset="doc/assets/readme/en/hero-dark.png" /> <img src="doc/assets/readme/en/hero-light.png" alt="pi Desktop: a finished turn in the timeline, with the Git diff open in the Review panel" /> </picture>

pi Desktop is not another agent. It runs the pi SDK in a background worker and reads the same files as the CLI — sessions, model logins, settings.json, installed extensions. Open a project and the sessions you started in the terminal are already in the sidebar; continue any of them, or start a new one.

At a glance

<img src="doc/assets/readme/en/overview.png" alt="Overview: timeline steps, side-by-side review, parallel sessions, @ file references, context breakdown, built-in adapters, themes and the shared ~/.pi/agent files" width="100%" />

One turn, start to finish

<img src="doc/assets/readme/en/agent-turn.gif" alt="A prompt is sent; the agent runs tests, reads a file, edits it, reruns tests, and the changes appear in Review" width="100%" />

_{Recorded from the app itself. The model replies come from a scripted local endpoint so the demo is reproducible; the <code>bash</code>, <code>read</code> and <code>edit</code> tools ran for real on the sample repo.}

Timeline

Tool calls stream in as flat steps — thinking, commands, reads, edits — and fold into one summary line once the answer starts. Each edit shows +N −M; the turn ends with a Files changed card that opens the file in Files or Review.

<img src="doc/assets/readme/en/timeline.png" alt="Expanded tool steps: thinking, ran node --test, read src/links.mjs, edited src/links.mjs and README.md" width="100%" />

Markdown, code blocks, KaTeX and long outputs render in place. Hover a message to copy it, rewind to it, or fork a new session from it.

Review

<img src="doc/assets/readme/en/review-stage.gif" alt="The right sidebar is dragged wider, the Git diff of links.mjs switches to side by side, and one hunk is staged" width="100%" />

Pick a scope — this turn, this session, or the whole Git working tree — and expand a file for its diff; drag the sidebar wider for a side-by-side view. Hunks can be staged or unstaged one at a time, and a line comment goes straight back into the conversation.

Files

<img src="doc/assets/readme/en/files-preview.gif" alt="links.mjs opens in the Files panel, links.test.mjs opens in a second tab, a line is quoted into the composer, and the preview expands over the chat column" width="100%" />

• Browse the project next to the chat; Ctrl/⌘+click opens a file in another tab.
• The gutter button quotes path:line into the composer as a reference.
• Expand preview gives the file the whole chat column; click again to go back. Drag a file onto the composer to attach it.

Composer

<img src="doc/assets/readme/en/composer-mention.gif" alt="Typing @li suggests src/links.mjs; Enter inserts it as a file chip" width="66%" />

• @ searches project files (respects .gitignore, uses fd) and inserts them as references.
• / lists pi's built-in commands and the ones your extensions register.
• Paste or drop images and files; model and thinking level sit at the right of the input.
• While the agent is working, Enter steers the current turn and Alt+Enter queues a follow-up for when it finishes.

Parallel sessions

<img src="doc/assets/readme/en/parallel-sessions.gif" alt="A fix turn starts, a second session starts a read-only turn, both run at once while the view switches between them" width="100%" />

Each session runs in its own worker. Start a turn, open another session and start a second one: both keep going, the sidebar marks the ones that are working and the status bar counts them. Settings → General sets how many workers stay alive and when idle ones are reclaimed; running sessions are never reclaimed.

Built-in terminal

<img src="doc/assets/readme/en/terminal.gif" alt="Ctrl+` opens a shell in the project under the chat; git log and the tests run, a second shell opens beside it and is closed again on its own" width="100%" />

Ctrl+` pulls a terminal up from under the chat, in the current project. It starts the same shell pi runs commands in (Git Bash on Windows) with pi's tools on PATH; + also offers PowerShell 7, Windows PowerShell, cmd, each WSL distribution, zsh or fish. Tabs and up to four side-by-side panes per tab — drag the borders, close one pane with its ✕ or Ctrl+Shift+W. Hiding the drawer keeps the shells and their output; selected output goes into the composer with one click.

Branches

<img src="doc/assets/readme/en/branches.gif" alt="The status bar shows main; the branch picker opens, filters to feat/remote-checks and switches to it" width="80%" />

The status bar shows the project's branch, uncommitted changes and ahead / behind. Click it (or Switch branch… in the command palette) to search local and remote branches, switch, or create one from HEAD. Changes travel with the switch when Git allows it; when they would be overwritten you can stash them first, and they are offered back when you return to the branch. If a session is still working in the project you are asked before anything changes under it.

Usage

<img src="doc/assets/readme/en/usage.png" alt="Settings → Usage for 90 days: cost, tokens, requests and cache hit rate, a stacked daily chart with one day hovered, and an activity heatmap" width="100%" />

Settings → Usage adds up tokens and cost from every pi session on the machine — the desktop's and terminal pi's, including a custom sessionDir — by day, hour, model, project and session. Hover a layer of a day for its share; replies copied into a fork count once.

More panels

<img src="doc/assets/readme/en/panels.png" alt="Tree panel with the session as a tree, Run panel with the context breakdown ring, and the Context panel listing context entries with token estimates" width="100%" />

Panel	What it does
Tree	The session as a tree, like pi /tree: filter to user messages, jump back to any node and continue from there as a new branch.
Run	Run state, model and thinking level, and how the context window splits between user, assistant and tool messages.
Context	The messages that make up the current context, with token estimates per entry.

Themes and background

<img src="doc/assets/readme/en/themes.png" alt="The Claude theme: warm ivory with serif replies in light mode, and warm charcoal over a soft background image in dark mode" width="100%" />

Light and dark each take a preset — Claude, VS Code Light+, Codex Dark — or your own: colours for the sidebar, chat, your messages, code blocks and borders, a heading / reply font (serif included), chat text size and line height, corner radius and shadow. Everything is a CSS variable, listed next to the custom CSS editor. A background image can sit behind the window — per mode or shared, with its strength, blur and the panes' opacity adjustable; text always stays on a frosted surface. Themes import from pi-theme-v1 / codex-theme-v1 strings; five icon sets and 90–110% density are in Settings → Appearance too.

pi on your phone

<img src="doc/assets/readme/en/phone.png" alt="pi Remote on Android: the inbox of sessions, a session with its tool steps and changed files, a diff with a line comment, and the session panel with context, changes, branches and cost" width="100%" />

pi Remote (Android) connects to the desktop app: turn on Settings → Mobile, scan the QR code, and every session is on the phone — read along while a turn runs, answer its questions, send prompts with images, pick the model and thinking level. Review a turn's changes or the working tree file by file, long-press lines to leave comments that go into your next message, switch the session's branch or fork from any message. The connection is end-to-end encrypted and stays on your network; away from home, put both devices in the same Tailscale / ZeroTier / WireGuard network (the app finds the overlay address, or add one by hand). English and Chinese follow the phone's language, with an in-app override.

How it fits together

<picture> <source media="(prefers-color-scheme: dark)" srcset="doc/assets/readme/en/architecture-dark.png" /> <img src="doc/assets/readme/en/architecture-light.png" alt="Terminal pi and pi Desktop both read and write ~/.pi/agent; pi Desktop has a renderer, a main process, and one worker per session" width="100%" /> </picture>

The renderer never talks to the SDK directly: the main process routes each request to the worker that owns the session, and that worker runs the pi SDK on your machine or inside a WSL distribution. Sessions, logins and settings stay in ~/.pi/agent, so the CLI and the app can take turns on the same session.

Also included

Extensions, unchanged	Extensions you installed for terminal pi load here. Their dialogs, tool cards, panels and /commands are mapped to native UI by declarative adapters — 36 ship built in. List
Notifications	A system notification and an in-app inbox when a turn finishes or needs input; the status bar shows what is running.
WSL runtime (Windows)	Run the worker inside a chosen WSL distribution, with sessions, Git and previews resolved on the Linux side.
Chinese / English UI	Switch in Settings; the phone app follows the system language.
Updates	Checks GitHub Releases in the background and can download and launch the installer.

Install

Platform	Package
Windows x64	pi.Desktop-Setup-<version>-x64.exe (installer) or pi.Desktop-Portable-<version>-x64.exe
macOS	.dmg / .zip for Apple Silicon (arm64) and Intel (x64)
Linux x64	.AppImage or .deb
Android 9+ (arm64)	pi-remote-<version>-android-arm64.apk — the phone app

Get them from Releases; each release lists SHA-256 checksums in SHA256SUMS.txt. The app bundles its own pi SDK; you only need to sign in to a model provider once, the same way you do for terminal pi (the credentials live in ~/.pi/agent). Settings → Runtime can switch to a globally installed pi version.

<details> <summary>Build from source</summary>

Requires Node.js ≥ 22.19.

git clone https://github.com/justhil/pi-app.git
cd pi-app
npm install
npm run dev          # development
npm run build        # production bundle in out/
npm run package      # installers via electron-builder

</details>

First five minutes

1. Open folder — the folder becomes the agent's working directory. For a throwaway chat, use + next to Conversations instead.
2. Pick a session — sessions from terminal pi for that folder are listed; + next to the project starts a new one.
3. Send — Enter sends, Shift+Enter adds a line.
4. Look right — Review, Run, Context, Tree and Files share the right sidebar; drag its edge to make it wider.
5. Go back — hover a message to rewind or fork, or press Esc twice in an empty composer to open the session tree.

Shortcuts

Action	Keys
Send / new line	Enter / Shift+Enter
Steer the running turn / queue a follow-up	Enter / Alt+Enter while running
Pull the last queued message back	Alt+↑
Stop	Esc
Session tree	Esc Esc in an empty composer
Previous / next sent message	↑ / ↓ with an empty composer or the caret at the start / end
File reference / command	@ / /
Open a file in a new tab	Ctrl/⌘+click in Files
Show / hide the terminal	Ctrl+`
Close the focused terminal pane / find in it	Ctrl+Shift+W / Ctrl+Shift+F (⌘W / ⌘F on macOS)

Extensions

Install and enable extensions exactly as for terminal pi:

pi install npm:<package>      # or: pi install git:github.com/<owner>/<repo>

then make sure the package is enabled in ~/.pi/agent/settings.json → packages and start a new session. Settings → Extensions shows what the current worker loaded; Settings → Adapters holds each adapter's desktop options. To override or add an adapter, put a .json adapter file in ~/.pi/desktop/adapters/ (or <project>/.pi/desktop/adapters/, which takes precedence) — see the authoring guide.

<details> <summary>Voice input</summary>

The mic button in the composer transcribes speech into the input. By default it uses the built-in service, which calls ChatGPT's transcription endpoint with your Codex / ChatGPT sign-in — no OpenAI API key and no local process. In Settings → Voice, paste an access_token or import it from ~/.codex/auth.json (written by codex login), then Verify login.

Under Advanced you can use a local codex-asr CLI or your own codex-asr serve URL instead. Typing always works without voice.

</details> <details> <summary>FAQ</summary>

Problem	Try
An extension is listed in Settings but missing in chat	Enable it in packages, then start a new session.
The first switch to a long session is slow	Only the latest messages load first; the rest loads on scroll or when you send.
Closed an extension dialog by accident	Use Continue on its timeline card.
Voice says the login is invalid	The token expired — run codex login again and re-import.
Blank window after changing source	Delete node_modules/.vite and rerun npm run dev.

</details> <details> <summary>For developers</summary>

• Stack: Electron 43 · React 18 · TypeScript · Tailwind · Zustand · i18next · xterm.js · @earendil-works/pi-coding-agent
• Processes: Electron main (IPC, worker pool, Git, previews) → one utility-process worker per session running the pi SDK → renderer.
• Checks: npm run test:unit, npm run test:scripts, npm run typecheck, npm run lint
• Docs: doc/ · adapter authoring · changelog
• Phone app: Kotlin / Compose in apps/mobile; node scripts/remote-dev-host.mjs runs a fake desktop to develop against.
• Releases: pushing a v* tag runs .github/workflows/release.yml and builds Windows, macOS, Linux and Android packages.

</details>

Support

Questions and feedback: LinuxDo or GitHub Issues. If the app is useful to you, a ⭐ helps other pi users find it, and you can sponsor maintenance with the QR code below.

<img src="doc/assets/sponsor-qr.png" alt="Sponsor QR code" width="200" />

License

MIT