# pi-gui is an Electron shell around the pi coding agent, not a second agent

> pi-gui gives the pi coding agent a desktop interface with parallel threads, a diff review tab, a real terminal and a command palette, and it is deliberately a shell rather than a new agent, since sessions, models, auth and tools all run through pi itself. The interesting engineering is in the main, preload and renderer boundary and in the release plumbing around it.

**minghinmatthewlam/pi-gui** — Electron GUI app for the pi coding agent runtime

- Repository: https://github.com/minghinmatthewlam/pi-gui
- Website: https://www.pi-gui.com/
- Stars: 1,303 · Forks: 187
- Language: TypeScript
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/minghinmatthewlam-pi-gui

## A shell around pi, and why that matters

pi-gui is the desktop app for the pi coding agent, and the first thing the readme establishes is what it is not.

It is a desktop shell around @earendil-works/pi-coding-agent, not a separate agent. Sessions, models, auth and tools all run through pi itself, so anything you set up with the pi CLI carries over.

That single decision shapes everything else. Because the runtime is pi, the configuration you already have works, and a thread in pi-gui is a pi session rather than a bespoke object. The quickstart says it plainly: pi-gui reads and writes pi's own session files and settings, so threads, credentials and skills are shared with the pi CLI.

The product promise is stated as running agents in parallel threads, each in its own git worktree if you want one, reviewing every change, running the tests in a real terminal, and shipping without leaving the window. The hero recording shows exactly that sequence, an agent fixing a bug, adding a test and running it, then the change opening for review.

The implementation is TypeScript on Electron, the licence is MIT, and the project moved to a 1.0 quickly, with v1.0.0 on 2026-09-25, v1.0.1 on 2026-09-26 and a long beta tail behind it at v0.1.0-beta.40. The last push was on 2026-10-14.

## Threads, worktrees and the sidebar

Every task gets its own thread. You start it in your checkout or in a fresh git worktree, then you start the next one while the first is still working.

The worktree option is the important one. A coding agent that edits files while you are working in the same checkout is a recipe for conflict, so giving each thread its own git worktree means several agents can run against the same repository at the same time without stepping on each other. It also gives you a natural unit of discard, since a worktree can be thrown away.

The sidebar is the view onto that. It shows what is running, what finished and what needs you. You can pin threads, group them by time or workspace, and archive the ones you are done with.

Those three states, running, finished and needs you, are the ones a person actually has to act on. The third is the interesting one, because an agent that is blocked on a decision is the one case where a background thread cannot proceed without you, and having it surfaced rather than buried in a log is the difference between using agents in parallel and being afraid to.

The agent side of the parallelism is in the feature list too. Threads that run threads means an agent can start, read and message other threads, and those show up in the sidebar like any other. And fork and rewind lets you fork a thread from any message into the same checkout or a new worktree, with the session tree navigable through the slash command /tree.

## The Review tab is the reason to use a GUI at all

The Review tab shows exactly what the agent touched, and the three ways of looking at it are the design decision.

You can compare uncommitted work, a branch against its base, or a single turn. Then you stage or unstage it file by file.

Single turn is the one that changes how you work with an agent. A diff of a whole branch tells you what changed, but it does not tell you which of the agent's actions caused the change. A diff of one turn tells you that the agent added this test, or that it changed this line in that step, which is the granularity you need when you are deciding whether to keep the change or revert it.

And staging is a real staging. The readme says you can stage or unstage file by file, which means the Review tab is not a viewer, it is a staging area. The natural workflow is to read a change the agent made, stage the part you agree with, and leave the rest unstaged for a follow-up prompt. That workflow is the clearest example of what the GUI adds over the CLI it wraps.

The review screenshots in the readme show a diff of an agent's change to a file called src/price.js, which is a small hint about what the project is for.

## The workbench, the palette and the rest

The workbench beside the conversation holds a real terminal, a file explorer and editor, the review tab, your worktrees, and tabs from desktop extensions. Each task keeps its own layout.

That last clause is the design point. A workbench that is shared between threads means the terminal shows one thing and the diff shows another, and you are constantly reorienting. Giving each task its own layout means the terminal, the files and the diff for a task are always the ones you are looking at.

On top of that sits a command palette that lists recent chats and actions, and the keyboard table is a strong signal of how the application is meant to be used. The shortcuts cover searching chats, workspaces and actions, opening any file in the current checkout, switching between recent threads, jumping to a thread in the sidebar, toggling the terminal, toggling the Review tab, and showing or hiding the workbench.

Two of them are about steering a run rather than navigating the interface. Pressing Enter while a run is going queues a follow-up, and pressing the modifier with Enter steers the current run. So you can queue the next instruction ahead of time and still interrupt or redirect the one in progress.

The rest of the feature list is wide but specific. Scheduled tasks let pi rerun a prompt on a schedule, such as a weekly dependency check, while the app is open. Skills and extensions can be switched on and off, tried from the composer, and desktop extensions get their own workbench tabs. Any provider works, with OAuth, an API key or a custom endpoint, and the model and thinking level are chosen per thread. The composer accepts at-mentioned files and pasted or dropped images. Notifications tell you when a background thread finishes, fails or needs you. And there are light and dark themes plus presets including Catppuccin, Tokyo Night, Nord, Dracula, Gruvbox and GitHub.

## Installing, and the platform caveats

pi-gui runs on macOS with Apple Silicon, Linux on x64 and Windows on x64, and the install is a download from the releases page. You get a dmg on macOS, an AppImage or a deb on Linux, and an exe on Windows.

The macOS path is the smoothest. You drag pi-gui.app into Applications, and the releases are signed and notarised, so nothing stops at the Gatekeeper. On Linux you make the AppImage executable and run it, or install the deb. On Windows you run the setup exe, or use the portable exe, and there is a caveat: the builds are not code-signed yet, so SmartScreen may ask you to confirm.

That Windows caveat is the one to warn your team about. A SmartScreen prompt on every install is the kind of friction that makes people download the thing from somewhere else, and it is a temporary problem that the project has plainly not solved yet.

There is a Homebrew cask as well.

```bash
brew tap minghinmatthewlam/tap
brew install --cask pi-gui
```

And updating with brew upgrade --cask pi-gui, with a note that a Homebrew upgrade may ask you to re-confirm macOS permissions or Dock placement, because the upgrade replaces the application bundle and the permissions are tied to it.

Other installs tell you when a new release is out and you update from the releases page. Building from source is for contributors.

## The Electron boundary, and the adapter over pi

The architecture section is the part of the readme that a security minded reviewer will read twice, because an Electron app that runs a coding agent with a terminal is a privileged application.

pi-gui is an Electron app with a tight main, preload and renderer boundary, on top of the pi runtime.

The renderer, at apps/desktop/src, is the React UI including the timeline, composer, workbench and settings, and it talks to the main process only through a typed IPC surface. The preload, at apps/desktop/electron/preload.ts, is the narrow bridge that exposes that IPC surface, and the renderer gets no broad Node access. The main process, at apps/desktop/electron, owns windows, session supervision, worktrees, terminal PTYs, scheduled tasks, notifications and persistence. And packages/pi-sdk-driver is a thin adapter over @earendil-works/pi-coding-agent.

So the renderer cannot reach the file system, spawn a process or read an environment variable. Everything goes across a typed channel, and the process that owns the terminal PTYs and the worktrees is separated from the UI that displays them.

That is a sound arrangement for an application that runs shell commands and edits your repository, and it is the kind of boundary that is cheap to design in and expensive to retrofit.

The repository layout follows the same split, with apps/ holding the desktop application and the website, packages/ holding the SDK driver, and the media assets living under apps/website/public/media, which is where the hero recording and the screenshots in the readme come from.

## The repository is as much release engineering as application code

The top level listing shows a workspace with more in it than the readme explains, and the package scripts explain what all of it is for.

The workspace is managed with pnpm at a pinned version, with a pnpm-workspace.yaml and a pnpm-lock.yaml, and the scripts are filtered by workspace package. The dev script runs the desktop package, the build script builds the desktop application and then the website, and there is a cluster of marketing scripts for product media, showcase captures and video rendering, which tells you the project treats its own documentation as a product artefact.

The verification scripts are the most revealing part. There is verify:install-copy, verify:release-config, verify:release-version, verify:homebrew-flow, and a test for the Homebrew tap update, and there are node tests for the release artifacts, the GitHub release state, the GitHub download retry and the Linux release verification. Each of those is a script that checks a specific part of the publishing pipeline.

That is a large share of the scripts for a 1.0 application, and the reason is obvious once you look at the install section. The project ships on three platforms with different packaging formats, a Homebrew tap, notarised macOS builds, unsigned Windows builds and a set of release assets, and every one of those is a thing that can be broken silently by a change elsewhere. The scripts exist because the failure mode of a broken release URL is a support conversation rather than a build error.

The rest of the tree is a well organised pnpm workspace, with a packages/ directory for shared code, an examples/ directory with a desktop extensions example, a patches/ directory, a tools/ directory, docs/ and plans/ directories, an eslint config at the root, a Playwright config for end to end tests, and the usual agent and tooling files such as AGENTS.md, CLAUDE.md and CONTRIBUTING.md.

## Conclusion

Adopt pi-gui when you drive the pi coding agent from a terminal today and want the work to be reviewable in a window, with several agents running at once in separate worktrees and the diff before it lands. Do not adopt it if you need an independent agent, because everything runs through pi and the readme is explicit that it is not a separate agent. Verify first which platform build you can use, since the Windows builds are not code signed yet and the macOS release is Apple Silicon only, and check that your pi configuration carries over, because pi-gui reads and writes pi's own session files and settings.

## FAQ

### What is pi-gui?

It is the desktop app for the pi coding agent, an Electron shell around @earendil-works/pi-coding-agent rather than a separate agent. Sessions, models, auth and tools all run through pi itself, so anything set up with the pi CLI carries over.

### How do I install pi-gui?

Download the latest dmg for macOS, AppImage or deb for Linux, or exe for Windows from the releases page. On macOS you can also use Homebrew with brew tap minghinmatthewlam/tap followed by brew install --cask pi-gui.

### Is the Windows build signed?

Not yet. The README says the Windows builds are not code-signed, so SmartScreen may ask you to confirm, while the macOS releases are signed and notarised so no Gatekeeper bypass is needed.

### Can I run several agents at the same time?

Yes. Every task gets its own thread, and you can start it in your checkout or in a fresh git worktree, then start the next one while the first works. The sidebar shows what is running, what finished and what needs you.

### What can the Review tab do?

It shows exactly what the agent touched. You can compare uncommitted work, a branch against its base, or a single turn, and then stage or unstage the result file by file, which makes it a staging area rather than only a viewer.

### How does pi-gui protect the renderer process?

It keeps a tight main, preload and renderer boundary. The renderer talks to the main process only through a typed IPC surface exposed by the preload, so it gets no broad Node access, while the main process owns the windows, worktrees, terminal PTYs, notifications and persistence.

## Sources

- [License: MIT](https://github.com/minghinmatthewlam/pi-gui/blob/main/LICENSE)
- [minghinmatthewlam/pi-gui on GitHub](https://github.com/minghinmatthewlam/pi-gui)
- [Project website](https://www.pi-gui.com/)
- [README](https://github.com/minghinmatthewlam/pi-gui/blob/main/README.md)
- [Releases](https://github.com/minghinmatthewlam/pi-gui/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/minghinmatthewlam-pi-gui