Pi Desktop

A desktop GUI for the Pi and oh-my-pi coding agents. Chat, manage projects, browse files, run commands, and install packages in one window.

Still in alpha, so expect rough edges.

What it does

• Streaming chat with thinking blocks, tool use, and rich rendering: bundled fonts and color emoji, inline SVG preview, and clickable file links that open a preview pane. Consecutive tool calls fold into collapsible groups. File reads show as line-numbered, syntax-highlighted code and edits as diffs
• Find within a conversation (Ctrl/Cmd+F); streaming follows new output only while you're at the bottom, with a jump-to-bottom control
• Composer file mentions (type @ to insert a path reference for Pi to read) and Up/Down to recall prompts sent in the current session
• Home dashboard with usage stats: messages, tokens, active-day streaks, peak hour, and a per-model breakdown
• Multi-Agent Council Planning, where Pi, Claude, and Codex plan together and reach consensus before Pi builds (opt-in)
• Quick switcher (Ctrl/Cmd+K) for skills, prompt templates, built-in commands, workspaces, sessions, and files; / in the composer for commands
• Skills browser, session fork/branch tree, and one-click context compaction
• Session naming (read from Pi) with inline rename, and a themed in-app confirmation for delete
• Custom models & providers editor in Settings, which edits your engine's models file (~/.pi/agent/models.json for Pi, ~/.omp/agent/models.yml for OMP)
• Multiple workspaces, with an independent agent process per live session, so a turn keeps running when you switch away from it; Mission Control and sidebar activity dots surface background work across projects, with optional desktop notifications when a session finishes, fails, or waits for approval
• New Task launcher starts a real fresh Pi session in a selected project, optionally in an isolated Git worktree, and sends the issue immediately while work continues in the background; matching task metadata, explicit branches, and GitHub PR URLs reuse an existing local worktree when found
• Diff Review conveyor with explicit Commit → Push → PR actions, upstream-aware GitHub CLI PR creation, and exact notification clicks back to the finished session
• Diagnostics view: Pi/OMP install and PATH resolution, provider configuration, permissions, and recent errors
• Review rail (toggleable) with permissions, approvals, changed files, and session status
• Custom permission rules: allow/deny glob rules per Pi tool that refine the permission modes, with per-workspace rule files, import/export, and live edits that apply without restarting Pi
• File tree, code/image/PDF/HTML preview panes, code editor (CodeMirror 6 with syntax highlighting), diff viewer, file search
• Terminal with ANSI colors
• Package browser connected to pi.dev/packages, with instant local search
• Session tags, model switching, live-preview settings, themes (7 built-ins plus System, and custom themes you can create in-app, import, export, or install from a URL)

Review rail

The right-side Review rail keeps safety and working-tree state visible while you chat with Pi. Toggle it from the chat toolbar (hidden by default, so it doesn't compete for space with file/image previews).

Changed files use readable status badges:

Pi and OMP engines

Pi Desktop speaks Pi's RPC protocol directly, so it can run either the standard pi CLI or the compatible omp binary from oh-my-pi. Settings → Agent Configuration → Agent Installation scans for installed engines, lets you select one, and also supports a custom executable or install directory.

Each engine keeps its own sessions: Pi writes to ~/.pi/agent/sessions, OMP to ~/.omp/agent/sessions. The app reads both, so switching engines never hides your history. When sessions from both appear in one list, each row is tagged Pi or OMP, and opening one starts the engine that wrote it.

OMP's protocol-v2 large-frame transport is negotiated automatically, and model-specific thinking efforts, including max, are shown when advertised. Its native read, grep, and glob tools are used for Plan / Read-only mode, and its plugin install/update/remove verbs are mapped behind the existing package actions.

Permissions

Four base modes control what Pi may do, selectable from the Review rail or Settings → Behavior:

Custom permission rules refine the modes with allow/deny rules per Pi tool, edited in Settings → Behavior → Permission rules:

• A rule is an action (allow/deny), a tool name (bash, edit, write, read, … or * for any), and an optional glob pattern matched against the tool's input: the shell command for bash, the file path for file tools. * is the only wildcard.
• Precedence: deny beats allow, and allow beats the mode default. Deny rules are enforced in every mode; a deny * *.env* rule holds even in Trusted. Allow rules skip the confirmation prompt in the ask modes.
• Rule edits apply to the next tool call without restarting Pi.
• Rules come in two scopes. The Global | This workspace tabs edit either your global rules or the active workspace's .pi-desktop/permission-rules.json. A workspace file is gated by workspace trust: once you trust the workspace it fully replaces the global list while you work there. Until then (the default for a repo you just opened) only its deny rules apply, layered on top of your global rules, and its allow rules are ignored, so a cloned repo can tighten your permissions but never loosen them. Opening a workspace whose file contains allow rules prompts you to trust it; you can also Trust/Revoke from the This workspace tab. Import/Export moves rule lists as JSON files, and the workspace file can be hand-edited or committed with a repo. The app picks up changes live.
• One honest caveat: rules match raw strings, with no path canonicalization or command parsing. Treat them as a guardrail against accidents rather than a security sandbox, and keep even a trusted workspace's allow rules narrow.

Example rules:

{ "action": "allow", "tool": "bash", "match": "npm test*" }
{ "action": "deny",  "tool": "bash", "match": "rm -rf *" }
{ "action": "deny",  "tool": "*",    "match": "*.env*" }

Custom themes

Pi Desktop ships 7 built-in themes (Dark, Light, Nord, Gruvbox, Breeze Dark, Breeze Light, Breeze Claudius) plus System, and you can create your own from Settings → Appearance.

To build one in the app, click Create theme to fork the currently active theme, or Edit theme to keep editing one you already created. Pick 7 seed colors (app background, surface, text, accent, success, warning, error) and a dark or light kind; every other color in the app is derived from those seeds. Changes preview live across the whole window as you edit. Two disclosures cover finer control:

• Advanced lets you override any of the ~30 derived tokens individually (borders, hovers, scrollbars, and so on) instead of accepting the automatic derivation.
• Syntax colors overrides the code-highlighting colors (keywords, strings, comments, etc.) used by the code editor and diff viewer.

Themes you create are listed alongside the built-ins in the Theme dropdown. Rename one by editing its name in the editor, duplicate one by selecting it and clicking Create theme (which forks whatever is active), and delete one with the Delete button that appears next to the dropdown whenever a custom theme is selected.

To share a theme, use Import and Export to move it as a .json file, or paste an https:// URL into Install from URL to fetch and install one directly (HTTP is rejected, and downloads are size-capped).

A theme file uses the pi-theme/v1 format: JSON with a $schema, a name, a kind ("dark" or "light"), and 7 seeds. That's enough for a complete, valid theme; everything else is derived automatically via CSS color-mix():

{
  "$schema": "pi-theme/v1",
  "name": "My Theme",
  "kind": "dark",
  "seeds": {
    "app": "#0a0a0a",
    "surface": "#171717",
    "text": "#f5f5f5",
    "accent": "#2563eb",
    "success": "#34d399",
    "warning": "#facc15",
    "error": "#f87171"
  }
}

Two optional top-level objects let you pin exact values instead of relying on derivation: overrides (any derived token, e.g. border, scrollbar, accent-hover) and syntax (code-highlighting colors, e.g. keyword, string, comment). Omit both and the theme still renders correctly from the 7 seeds alone.

User theme files live in the app's user-data directory under themes/ (on Linux, ~/.config/pi-desktop/themes/).

There's also a community gallery at pi-desktop-themes: copy any theme's raw URL into Install from URL, or submit your own with a pull request.

Multi-Agent Council Planning

Pi, Claude, and Codex each produce an initial plan, share and converge, and Pi presents the agreed consensus plan before anything is built. All members plan read-only; Pi is the only agent that edits files.

The feature is off by default. Enable it in Settings → "Multi-Agent Council Planning"; a confirmation dialog warns that it i