pi Desktop: a native window around the pi coding agent that shares its terminal state
An elegant GUI implementation of pi-agent
At a glance
- What is it?
- pi Desktop is an MIT Electron shell for the pi coding agent, adding a diff view, a clickable session tree and message queueing. It is not a separate AI: sessions, logins and extensions live in the same ~/.pi/agent files as the CLI.
- Who is it for?
- Adopt pi Desktop if you already use the pi coding agent in the terminal and want a real diff view, a clickable session tree and message queueing in a native window that shares the same ~/.pi/agent state: the extension adapters, which render your existing pi extensions natively with no package changes, are what keep it a shell rather than a fork. It is pointless if you do not use pi, since it is bound to that agent, and it carries an Electron footprint heavier than the CLI.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 12 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 17, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
A window around the terminal agent you already run
pi Desktop is the desktop app for the pi coding agent, the same agent you run in the terminal, given a timeline, side panels and a real window. The README is careful to say what it is not: not a separate AI, but a desktop shell around the pi SDK you already use, with conversations, model logins and extension settings living in the same `~/.pi/agent` files.
The user is an existing pi CLI user who has wished for the things a terminal cannot give: a real diff view instead of scrolling raw output, the ability to queue a follow-up while the agent is still running, and a clickable session tree instead of typing a tree command. pi Desktop provides those without forking pi or touching installed extensions.
That shared-state design is the whole point. Because sessions, auth, settings and extensions live in `~/.pi/agent` and are shared with the CLI, you can open a project in the desktop app and keep chatting from where you left off in the terminal. It is a view onto the same agent, not a parallel one, and it is MIT licensed, built on Electron.
The features a terminal cannot give you
The README's feature list is a catalog of terminal pain points solved by a GUI. The streaming timeline renders markdown, code blocks, KaTeX math and foldable tool steps for read, edit and bash with line-level diffs, which is the diff view scrolling raw output cannot provide. The session tree lets you branch and rewind like the CLI tree command, but clickable, and with git it can optionally restore files on jump.
The composer adds inline file attachments, image paste, model and thinking-level pills and a slash-command menu, with a Files panel that supports dragging files into the composer or right-clicking to attach. Message queueing lets you keep typing while the agent runs, executing when the current turn ends, which removes the wait the terminal forces.
Crucially, the README says the full pi package ecosystem works here: every extension installed for terminal pi, its dialogs, tool cards, side panels and slash commands, is translated to native UI by per-extension adapters, with no changes to the npm packages. That adapter approach is what lets the desktop app present extensions natively without forking them, and it is the same pattern that keeps the app a shell rather than a fork.
Getting the app and the one prerequisite
pi Desktop is distributed as prebuilt releases. The README directs Windows users to download the installer or portable build from the Releases page, and the badges show the current version as 0.5.4 with a bilingual Chinese and English UI toggle in Settings.
The one prerequisite the README is explicit about is that you need pi itself set up once on the machine, model login and configuration, because the desktop app is a shell around the existing pi SDK rather than a self-contained install. It reads and writes the same `~/.pi/agent` files, so those must exist and be configured.
Developers can build from source, which the README documents directly:
git clone https://github.com/justhil/pi-app.git
cd pi-app
npm install
npm run devThe repository is an Electron project using electron-vite and electron-builder, with a `packages/` layout and end-to-end tests, and it documents adapters separately for the extension-translation layer. For a user, the path is straightforward: set up pi in the terminal first, install the desktop release, open a project, and the app shows the same sessions and extensions the CLI already has. There is optional voice input via a bundled codex-asr binary for local transcription, which is off unless you enable it.
The limitation: it is bound to pi, and to Electron
The honest limitation is dependency. pi Desktop is a shell around pi, so it is only useful if you use the pi coding agent, and it inherits whatever pi does and requires. It is not a general agent GUI; a user not already invested in pi gets nothing from it. The README's framing as not a separate AI is honest, but it means the app's value is entirely a function of pi's.
The shared-state design is a strength and a subtle risk: because the desktop app and the CLI read and write the same `~/.pi/agent` files, they are two front-ends onto one state, and a user should understand that changes in one are changes to the shared configuration, not an isolated copy. That is the intended behavior, but it is worth knowing before running both against the same project.
Electron is the other cost. A native window built on Electron carries the usual memory and disk footprint of a bundled browser runtime, which is heavier than the terminal it wraps. For the diff view, session tree and queueing that is a reasonable trade, but it is a trade, and the terminal remains the lighter option for anyone who does not need the GUI features.
Against the pi CLI, and against a different agent's GUI
The most direct comparison is the pi CLI itself, since pi Desktop wraps it. The CLI is lighter and scriptable and is the source of truth; pi Desktop adds a diff view, a clickable session tree, message queueing and native extension UI on top of the same state. If you live in the terminal and do not miss those, the CLI is enough. If scrolling raw diffs and typing tree commands is friction, the desktop app removes it without changing the underlying agent.
Against a GUI for a different coding agent, pi Desktop's distinguishing choice is that it does not fork or reimplement the agent; it is a shell over pi's own SDK and files, translating existing extensions via adapters rather than requiring GUI-specific ones. That keeps it in lockstep with the CLI and avoids a second, diverging configuration. The trade is that it is tied to pi specifically. Choose the pi CLI for the lightest, scriptable path. Choose a different agent's GUI if you use a different agent. Choose pi Desktop when you already use pi and want the terminal's diffs, session tree and queued messages in a real window sharing the same state.
MIT, shared config, and what to check first
pi Desktop is MIT, so it can be forked and adapted with attribution, and its shell design means it does not lock you in: the source of truth stays in `~/.pi/agent`, which the CLI also uses, so uninstalling the desktop app leaves your sessions and configuration intact. That is a reassuring property for a GUI, since your work is not trapped in it.
Upgrade cost is the app's own release cadence, currently at 0.5.4, plus the underlying pi. Because extensions are translated by per-extension adapters with no changes to the npm packages, an extension update does not require an app change, though a brand-new extension may need an adapter to render natively rather than generically.
The concrete first step is to set up pi in the terminal before installing the desktop app, since the README requires pi configured once on the machine, then open an existing project and confirm the desktop app shows the same sessions the CLI does, proving the shared `~/.pi/agent` state is working. Try queueing a message while the agent runs and clicking through the session tree to see whether those specific GUI features justify the Electron footprint for your workflow.
Editorial conclusion
Adopt pi Desktop if you already use the pi coding agent in the terminal and want a real diff view, a clickable session tree and message queueing in a native window that shares the same ~/.pi/agent state: the extension adapters, which render your existing pi extensions natively with no package changes, are what keep it a shell rather than a fork. It is pointless if you do not use pi, since it is bound to that agent, and it carries an Electron footprint heavier than the CLI. Before relying on it, set up pi in the terminal first as the README requires, then open an existing project and confirm the desktop app shows the same sessions, and test message queueing and the session tree to judge whether those features justify the app for you.
Frequently asked questions
Is pi Desktop a separate AI from the pi CLI?
No. The README states it is a desktop shell around the pi SDK you already use, not a separate AI. Conversations, model logins and extension settings live in the same ~/.pi/agent files shared with the terminal pi.
Do I need the pi CLI installed to use pi Desktop?
Yes. The README says you need pi set up once on the machine, including model login, because the desktop app is a shell around the existing pi SDK and reads and writes the shared ~/.pi/agent files.
Do my terminal pi extensions work in pi Desktop?
Yes. The README says every extension installed for terminal pi works, with its dialogs, tool cards, side panels and slash commands translated to native UI by per-extension adapters, and no changes to the npm packages.
Community notes