A Codex-style desktop app for the pi coding agent.
pi-gui gives pi a native home on the desktop: a threaded timeline of your agent
sessions, git worktrees per thread, an integrated terminal and inline diff viewer,
and multi-agent orchestration — all backed by pi's own session files as the source
of truth. It is a UI shell around @earendil-works/pi-coding-agent,
not a separate agent runtime: session management, model/auth setup, and agent
execution all run through upstream pi.
Expanding a tool call, reviewing the diff panel, the integrated terminal, and a theme switch. (higher-quality MP4)
| Thread timeline (dark) | Thread timeline (light) |
|---|---|
 |
 |
| Inline diff viewer | Integrated terminal |
|---|---|
 |
 |
- Threaded timeline — each session renders as a timeline of messages and collapsible tool calls, Codex-style.
- Git worktrees per thread — start a thread in the workspace directly (
Local) or in an isolated git worktree so parallel work never collides. - Multi-agent orchestration — an orchestrator thread can spin up and supervise child worker threads.
- Integrated terminal — a real PTY terminal (via
node-pty) docked in the app. - Inline diff viewer — review changed files in a side panel (toggle with ⌘/Ctrl+D).
- Composer niceties —
@-mention files, and paste or drag-and-drop image attachments straight into the prompt. - Skills & extensions — manage
piskills and extensions from a dedicated view. - Appearance themes — light and dark, with selectable theme presets.
- Native notifications — get an OS notification when an agent run finishes.
- Session archive — archive threads you're done with to keep the sidebar tidy.
- Multiple providers — connect model providers via OAuth or API key under Settings → Providers.
pi-gui is in public beta for macOS (Apple Silicon) and Linux (AppImage).
Download the latest .dmg (macOS) or .AppImage (Linux) from the
Releases page.
On macOS, drag pi-gui.app into /Applications and launch it. Releases are signed
and notarized. To update, download the newer release and replace the app.
brew tap minghinmatthewlam/tap
brew install --cask pi-guiUpdate with brew upgrade --cask pi-gui. During beta, a Homebrew upgrade may prompt
you to re-confirm macOS permissions or Dock placement.
See Development. Building from source is intended for contributors, not as the primary install path.
- Install pi-gui and launch it.
- Open Settings → Providers and connect a model provider (OAuth or API key).
- Add a workspace (a local project folder).
- Click New thread, pick
LocalorWorktree, and send your first prompt.
You need valid model/provider authentication that pi supports; pi-gui uses pi's
auth and session state, so anything you've already configured with the pi CLI
carries over.
pi-gui is an Electron app organized around a tight main/preload/renderer boundary,
sitting on top of the pi runtime:
- Renderer (
apps/desktop/src) — the React UI: timeline, composer, diff panel, terminal, 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 to the renderer; the renderer gets no broad Node access. - Main (
apps/desktop/electron) — the Node side: windowing, session supervision, worktrees, terminal PTYs, notifications, and persistence. packages/pi-sdk-driver— a thin adapter from the desktop app to@earendil-works/pi-coding-agent. It stays close to upstreampiand does not fork or reimplement runtime behavior.- JSONL session files as the source of truth —
pipersists each session as a JSONL transcript on disk; pi-gui reads those files as the authoritative record for closed sessions rather than keeping a divergent copy.
Supporting packages: packages/session-driver (shared session driver types) and
packages/catalogs (lightweight workspace/session catalog state).
Requires Node 20+ and pnpm (managed via corepack). pnpm is
the supported package manager, and pnpm-lock.yaml is the authoritative lockfile.
corepack enable
pnpm installCommon commands (run from the repo root):
pnpm dev # run the desktop app in development (electron-vite, hot reload)
pnpm build # build all workspaces
pnpm typecheck # type-check all workspaces
pnpm lint # lint all workspaces
pnpm test # run each workspace's tests (desktop runs the core E2E lane)Desktop end-to-end tests use a Playwright + Electron harness and are organized into
lanes. The default pnpm test runs the core lane; to run everything:
pnpm --filter @pi-gui/desktop run test:e2e:all # core + live + nativeSee apps/desktop/README.md for lane details and
platform-specific packaging notes. Package a Linux AppImage locally with:
pnpm --filter @pi-gui/desktop run package:linuxapps/desktop— the Electron app (renderer UI + main/preload).apps/website— the marketing/landing site.packages/pi-sdk-driver— adapter over@earendil-works/pi-coding-agent.packages/session-driver— shared session driver types.packages/catalogs— workspace/session catalog state.
Contributions are welcome — see CONTRIBUTING.md for setup, verification expectations, and the desktop test lanes. Desktop changes are expected to be verified on the real Electron surface, not only by unit tests.
Native computer use is not built into pi-gui. Desktop/browser control is available
separately through the author's standalone
computer-use-mcp server,
which any MCP-capable agent can use.
- Built on
@earendil-works/pi-coding-agent. - Upstream runtime and ecosystem by
earendil-works/pi.
MIT © Matthew Lam
