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
CtrlTab
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 install --cask pi-gui
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:
Renderer (apps/desktop/src): the React UI, including the timeline, composer,
workbench and settings. It talks to the main process only through a typed IPC surface.
Preload (apps/desktop/electron/preload.ts): the narrow bridge that exposes that IPC
surface. The renderer gets no broad Node access.
Main (apps/desktop/electron): windows, session supervision, worktrees, terminal PTYs,
scheduled tasks, notifications and persistence.
packages/pi-sdk-driver: a thin adapter over @earendil-works/pi-coding-agent. It stays
close to upstream pi and does not fork or reimplement runtime behavior.
Session files are the source of truth. pi stores each session as a JSONL transcript on
disk, and pi-gui reads those files rather than keeping its own copy.
Requires Node 22.19 or newer (CI runs Node 22) and pnpm through corepack.
pnpm-lock.yaml is the authoritative lockfile.
corepack enable
pnpm install
Common commands, from the repo root:
pnpm dev # run the desktop app with hot reload
pnpm check # CI baseline: format, lint, renderer boundaries, types, guard and driver tests
pnpm build # build the desktop app and the website
pnpm typecheck # type-check all workspaces
pnpm lint # correctness rules plus typed promise and unsafe-any checks
pnpm format # apply the shared formatter
pnpm test # each workspace's tests (desktop runs the core E2E lane)
pnpm marketing:media # re-record the README and website media from a real agent run
pnpm check is the shared local and CI baseline. It does not launch Electron or replace the
desktop, website-build and package CI jobs; see docs/ci-baseline.md.
Desktop end-to-end tests drive the real Electron app with Playwright, in lanes. pnpm test
runs the core lane; to run everything:
pnpm --filter @pi-gui/desktop run test:e2e:all # core + live + native
See apps/desktop/README.md for the lanes, packaging on each
platform, and how the product media is recorded.
Repository layout
apps/desktop: the Electron app (renderer, main and preload).
packages/catalogs: workspace and session catalog state.
packages/extension-ui: helpers for building desktop extension views.
examples/desktop-extensions: example extensions with their own workbench tabs.
video: the Remotion showcase video.
docs: architecture, CI and design notes.
.agents/skills: checked-in agent skills, including desktop verification.
Contributing
Contributions are welcome. See CONTRIBUTING.md for setup, verification
expectations and the desktop test lanes. Desktop changes should be verified on the real
Electron app, not only by unit tests.
Computer use
Native computer use is not built into pi-gui. Desktop and browser control is available
separately through the standalone
computer-use-mcp server, which any
MCP-capable agent can use.
pi-gui 是 pi 编码代理的桌面应用：你可以并行运行多个线程中的编码代理，审查它们做的每一处改动，在真实终端里运行测试，不用离开窗口就能交付成果。