Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
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.
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 buildRequirements: macOS 11+, Bun 1.3+, Node.js 24.13.1+. After Electron upgrades, run bun install so native modules (e.g. node-pty) rebuild.
bun install
bun run build
bun run devThat 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.
| 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 |
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.
| 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.
MIT-licensed. Issues and PRs welcome.
- Fork and branch from main
- Keep changes focused; add tests where they earn their keep
- Run bun run lint && bun run typecheck && bun run test before opening a PR