pi-gui
The desktop app for the pi coding agent.
Run agents in parallel threads, each in its own git worktree if you want one. Review every
change, run the tests in a real terminal, and ship without leaving the window. pi-gui 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.
A real run: the agent fixes a bug, adds a test and runs it, then the change opens for review. (Watch in full quality)
Features
Run agents side by side
Every task gets its own thread. Start it in your checkout or in a fresh git worktree, then
start the next one while it works. The sidebar shows what is running, what finished and what
needs you. Pin threads, group them by time or workspace, and archive the ones you are done with.
Review every change before it lands
The Review tab shows exactly what the agent touched. Compare uncommitted work, a branch
against its base, or a single turn, and stage or unstage it file by file.
Terminal and files in the same window
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.
Everything is a keystroke away
| Shortcut (macOS; use Ctrl on Linux and Windows) | Does |
|---|
| ⌘ K | Search chats, workspaces and actions |
| ⌘ P | Open any file in the current checkout |
| Ctrl Tab | Switch between recent threads |
| ⌘ 1 to 9 | Jump to a thread in the sidebar |
| ⌘ J | Toggle the terminal |
| ⌘ R | Toggle the Review tab |
| ⌘ ⌥ B | Show or hide the workbench |
| Enter while a run is going | Queue a follow-up |
| ⌘ Enter while a run is going | Steer the current run |
And the rest
- Scheduled tasks. Have pi rerun a prompt on a schedule, such as a weekly dependency
check, while the app is open.
- Skills and extensions. Turn pi skills and extensions on and off, try them from the
composer, and give desktop extensions their own workbench tabs.
- Any provider. Sign in with OAuth, paste an API key, or point at a custom endpoint.
Pick the model and thinking level per thread.
- Fork and rewind. Fork a thread from any message into the same checkout or a new
worktree, and move around the session tree with
/tree.
- Composer.
@-mention files, and paste or drop images into the prompt.
- Threads that run threads. An agent can start, read and message other threads, which
show up in the sidebar like any other.
- Notifications. Get told when a background thread finishes, fails or needs you.
- Themes. Light and dark, plus presets like Catppuccin, Tokyo Night, Nord, Dracula,
Gruvbox and GitHub.
Install
pi-gui runs on macOS (Apple Silicon), Linux (x64) and Windows (x64).
Download the latest .dmg (macOS), .AppImage or .deb (Linux), or .exe (Windows) from the
Releases page.
- macOS: drag
pi-gui.app into Applications. Releases are signed and notarized.
- Linux: make the AppImage executable and run it, or install the
.deb.
- Windows: run the setup
.exe, or use the portable .exe. Builds are not code-signed
yet, so SmartScreen may ask you to confirm.
On macOS you can also use Homebrew:
brew tap minghinmatthewlam/tap
brew trust minghinmatthewlam/tap
brew install --cask pi-gui
Homebrew refuses to load casks from untrusted third-party taps, so the
brew trust step is required on first install.
Update with brew upgrade --cask pi-gui. A Homebrew upgrade may ask you to
re-confirm macOS permissions or Dock placement. Other installs tell you when a new release is
out and update from the Releases page.
Building from source is for contributors; see Development.
Quickstart
- Install pi-gui and open it.
- Open Settings → Providers and connect a model provider (OAuth or API key).
- Add a workspace: a local project folder.
- Click New thread, choose Local or Worktree, and send your first prompt.
pi-gui reads and writes pi's own session files and settings, so threads, credentials and
skills are shared with the pi CLI.
Architecture
pi-gui is an Electron app with a tight main, preload and renderer boundary, on top of the pi
runtime:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
