minghinmatthewlam/pi-gui

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 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

1. Install pi-gui and open it. 2. Open Settings → Providers and connect a model provider (OAuth or API key). 3. Add a workspace: a local project folder. 4. 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.

See docs/architecture.md for ownership and boundaries.

Development

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).
• apps/website: pi-gui.com.
• packages/pi-sdk-driver: the adapter over @earendil-works/pi-coding-agent.
• packages/session-driver: shared session driver types.
• 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.

Acknowledgements

Built on @earendil-works/pi-coding-agent and the pi runtime and ecosystem.

License

MIT © Matthew Lam