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.

Pi Desktop is in alpha, so expect rough edges.

What it does

• Streaming chat with thinking blocks and tool calls. Consecutive tool calls fold into groups, file reads show as line-numbered code, and edits show as diffs. SVG blocks render inline, and file names in replies open a preview pane
• Composer with @ file mentions, prompt recall with Up/Down, a model picker you can drive from the keyboard, and file or image attachments (pick, paste, or drop them)
• Find in the conversation (Ctrl/Cmd+F) and a quick switcher (Ctrl/Cmd+K) for commands, skills, prompt templates, workspaces, sessions, and files
• Multiple workspaces with project tabs you can drag to reorder. Each live session runs its own agent process, so a turn keeps running after you switch away. Mission Control and sidebar activity dots show background work, and desktop notifications tell you when a session finishes, fails, or waits for approval
• New Task starts a fresh session in a project and sends the task right away, optionally in an isolated Git worktree
• Linked tasks: one task across several Git repositories, shipped as linked pull requests
• Right-edge tool rail that opens the Review panel, file tree, diff viewer, and terminal
• Subagents panel with a live, read-only transcript for each subagent the chat starts (OMP, or Pi with pi-subagents)
• Diff viewer with a filter for the files the session touched, per-file discard, and a Git bar with Commit, Commit + Push, Push, and PR (it becomes Open PR #N when the branch has an open pull request). In the Commit dialog, Suggest message asks the session's model for a commit message, and new files are committed only if you check them. The status bar has a branch menu to switch branches or create a new one
• Code, image, PDF, and HTML previews, a CodeMirror 6 editor with Git change markers, and workspace file search
• Resizable terminal, one per workspace
• Permission modes and custom allow/deny rules, global or per workspace
• Workflow runs viewer for the pi-dynamic-workflows extension, with Abort and Resume
• Skills browser, session fork/branch tree, session tags, inline session rename, and one-click context compaction
• Home dashboard with usage stats: messages, tokens, active-day streaks, peak hour, and a per-model breakdown
• Diagnostics view: Pi/OMP install and PATH resolution, provider configuration, permissions, and recent errors
• Package browser for pi.dev/packages, with local search and update checks for installed packages
• Custom models and providers editor, which edits your engine's models file (~/.pi/agent/models.json for Pi, ~/.omp/agent/models.yml for OMP)
• Keyboard shortcuts you can change in Settings, themes (7 built-ins, System, and your own), and a UI font setting
• Multi-Agent Council Planning: Pi, Claude, and Codex plan together before Pi builds (opt-in)
• TypeSafe Jev: save your TypeSafe API key once and install the Jev skill for Pi and OMP (opt-in)
• Voice dictation that runs on your machine with a model you pick (opt-in)
• Translatable interface (English and Simplified Chinese ship today)

Review panel

The Review panel shows the permission mode, pending approvals, changed files, and session status while you chat with Pi. It is hidden by default. Open it from the right-edge tool rail or with Ctrl/Cmd+Shift+U.

Changed files use these status badges:

Pi and OMP engines

Pi Desktop speaks Pi's RPC protocol, so it can run either the standard pi CLI or the compatible omp binary from oh-my-pi. Settings > Agent Configuration > Agent Installation finds installed engines and lets you pick one, or point it at 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. Under OMP, package actions use OMP's plugin commands.

If ~/.pi/.env exists, its variables (provider API keys, for example) are passed to every Pi or OMP process and to the terminal. A variable already set in the environment wins.

Linked tasks

A linked task lets the agent change several Git repositories together, for example a library and the app that uses it. Start one from Linked task on the Home screen, the tab bar, or /linked-task.

• A repo set is a saved group of repositories with one main repository. The agent starts in the main one and follows its project rules. Make sets in the same dialog or with /new-repo-set.
• Isolated (default) gives each repository a new worktree, all on one new branch, so your own checkouts do not change. In place edits your checkouts on their current branches.
• The repo bar under the tabs lists the repositories. Select one to show it in the file tree, diff viewer, and Git bar. Add repo (or /add-repo) adds a repository while the task runs; the agent sees it on its next turn.
• Ship all commits, pushes, and opens a pull request in each changed repository, then lists the other pull requests in each description. Retry runs only the repositories that failed. It never ships from main, master, or the remote's default branch.
• Works with Pi and OMP.

A file edit outside the task's repositories always asks first, even in Trusted mode. Shell commands are not checked for paths: they follow your permission mode and rules like any other command.

Permissions

Four base modes control what Pi may do. Pick one in the composer, the Review panel, or Settings > Behavior:

The default is Ask before edits.

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

• A rule has an action (allow or deny), a tool name (bash, edit, write, read, and so on, or * for any tool), 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.
• Deny beats allow, and allow beats the mode default. Deny rules apply in every mode, so 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.
• The Global and This workspace tabs edit your global rules or the active workspace's .pi-desktop/permission-rules.json. A workspace file depends on workspace trust. After you trust the workspace, its file replaces the global list while you work there. Until then (the default for a repo you just opened), only its deny rules apply, on top of your global rules, and its allow rules are ignored. A cloned repo can tighten your permissions but never loosen them. Opening a workspace whose file has allow rules asks you to trust it, and the This workspace tab has Trust and Revoke controls. Import and Export move rule lists as JSON files. You can also edit the workspace file by hand or commit it with the repo; the app picks up changes live.
• Rules match raw strings, with no path canonicalization or command parsing. Treat them as a guard against accidents, not 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, the default. You can also create your own in Settings > Appearance. With System selected, Light Theme and Dark Theme choose which installed theme each OS mode uses.

Click Create theme to fork the active theme, or Edit theme to keep editing one you created. Pick 7 seed colors (app background, surface, text, accent, success, warning, error) and a dark or light kind. The app derives every other color from those seeds, and the whole window previews your changes as you edit. Two sections give finer control:

• Advanced overrides individual derived tokens (borders, hovers, scrollbars, and so on).
• Syntax colors overrides the code-highlighting colors (keywords, strings, comments, and so on) in the code editor and diff viewer.

Your themes appear next to the built-ins in the Theme dropdown. To rename a theme, edit its name in the editor. To duplicate one, select it and click Create theme. To delete one, select it and click Delete under Theme Actions.

To share a theme, use Import and Export to move it as a .json file, or paste an https:// URL into the field under Theme Actions and click Install. Plain HTTP URLs are refused, and downloads have a size limit.

A theme file uses the pi-theme/v1 format: JSON with a $schema, a name, a kind ("dark" or