Pi Desktop

Alpha

A native macOS desktop for the Pi coding agent—repos, worktrees, terminals, and chat in one place.

Install · Quick start · Features · Architecture · Development · Contributing

Caution

Alpha. Expect breaking changes and rough edges. Without the pi CLI installed, chat uses the built-in mock agent so the shell stays usable out of the box. Install pi (or set PI_CLI_PATH) for real CLI/SDK chat.

Tip

Grab the latest arm64 DMG from Releases, open it, and drag Pi Desktop into Applications.

Install

macOS (recommended) — download Pi Desktop-<version>-arm64.dmg from GitHub Releases.

From source

git clone https://github.com/tanRdev/pi-desktop.git
cd pi-desktop
bun install
bun run build
bun run --filter @pi-desktop/desktop dist:mac   # optional packaged build

Requirements: macOS 11+, Bun 1.3+, Node.js 24.13.1+. After Electron upgrades, run bun install so native modules (e.g. node-pty) rebuild.

Quick start

bun install
bun run build
bun run dev

That opens Pi Desktop with hot reload. Add a local git repository, create a worktree, and send a chat message—the mock agent answers when pi isn’t installed.

Features

Feature	Status	Notes
Repositories	Alpha	Browse and organize local projects
Worktrees	Alpha	Create / switch / remove isolated checkouts
Terminal	Alpha	Integrated node-pty terminal
Agent chat	Alpha	Mock by default without pi; CLI/SDK when available; in-app OAuth
Packages	Alpha	Catalog browse / install—expect rough edges
Auto-updates	Alpha	Packaged updater with Settings consent
Security boundary	Solid	Main ↔ Contracts preload ↔ renderer

Architecture

Monorepo with a hard Electron security boundary:

pi-desktop/
├── apps/desktop/          # Electron main, preload, React renderer
└── packages/
    ├── contracts/         # IPC channels + Effect Schema (single source of truth)
    ├── shared/            # Domain models and shared utilities
    ├── agent-host/        # Mock / CLI / SDK agent runtimes
    ├── shell-model/       # Pure shell + agent-feed state
    └── ui/                # Geist tokens, glass shell, shared primitives

• Main owns catalogs (versioned JSON persistence), git, terminals, windows, and the agent-host process.
• Preload exposes a typed Contracts client via contextBridge—no Node in the renderer.
• Renderer is React 19 + Zustand + Tailwind; all native work goes through IPC.
• Agent host runs in an isolated session-server child; context switches cancel stale setups so only the latest thread wins.

Development

Command	Purpose
bun install	Install deps, hooks, native rebuild
bun run dev	Electron + hot reload
bun run build	Build all workspaces
bun run lint	Biome
bun run typecheck	Typecheck all workspaces
bun run test	Vitest (unit + integration)
bun run test:e2e	Playwright smoke (mock agent)
bun run lint:contracts	IPC Contract coverage gate

# Packaged macOS build
bun run --filter @pi-desktop/desktop dist:mac
# → dist/release/Pi Desktop-<version>-arm64.{dmg,zip}

Pre-commit hooks live in .githooks/ and are wired by prepare on install.

Contributing

MIT-licensed. Issues and PRs welcome.

1. Fork and branch from main
2. Keep changes focused; add tests where they earn their keep
3. Run bun run lint && bun run typecheck && bun run test before opening a PR

License

MIT