Skip to content
ejpirPublic

About

Pi Gui

Resources

Stars

15 stars

Watchers

0 watching

Forks

Repository files navigation

Pi Desktop

A native desktop app for the pi coding agent, built with Zed's GPUI (no webview). Each session runs its own pi process in its project folder.

A tour of Pi Desktop on macOS A tour of Pi for Android
Pi Desktop on macOS Pi for Android
  • Sessions and projects in a sidebar, with search, forks and worktrees.
  • Thread with readable Markdown and Mermaid, the screenshots and HTML pages Pi made, collapsible tools, and a composer with / commands, @ mentions and attachments.
  • Changes as split or unified diffs; each run that edits files can become a jj change you can undo.
  • Files, terminal, language servers, models and settings in the same window.
  • Remote sessions over SSH that keep running when you disconnect (docs/remote.md).
  • Pi for Android follows sessions over SSH, edits remote files on Linux/macOS hosts, and opens an isolated remote terminal on Linux hosts. It can also run experimental Local chats on this phone with bundled Bun/Durable, Claude/Codex subscriptions and SQLite persistence. Local is not sandboxed; its tools use Android sh, not GNU Bash/Linux tools. Get pi-android-arm64.apk from the releases.

Build and run

Keep a checkout of Zed next to this repository (revision 5becf8b5910fd538ccc5489e8edd3fde32917fad):

repos/
  pi-desktop/
  zed/

Apply this repository's reviewed GPUI lifecycle/tracing patch to that exact checkout (CI does this automatically):

git -C ../zed apply ../pi-desktop/packaging/zed.patch

The patch is already applied if you are using the development checkout from this change; do not apply it twice.

You need rustup and CMake (macOS: Xcode Command Line Tools and brew install cmake).

Fetch pi's release build, point the build at it, and run:

python3 scripts/fetch_pi.py    # writes artifacts/pi/pi-<platform>.tar.gz
export PI_DESKTOP_BACKEND_ARCHIVE=$PWD/artifacts/pi/pi-darwin-arm64.tar.gz
cargo run --release --locked -p pi-desktop --features bundled-backend -- --project /path/to/project

On Linux, use the pi-linux-x64 or pi-linux-arm64 archive instead. pi is built into the app, so you don't need Node.js or pi installed. Your existing pi settings and sign-ins in ~/.pi/agent are reused.

Real sessions use your provider credentials and can edit files, just like pi. To try the app offline with sample sessions, add --demo.

To record the tour above again, run scripts/macos-demo/record.sh after a release build.

Native Visualize

Type @Visualize in desktop or Android chat to request an interactive native app. Buttons, sliders, vector canvases, keyboard/held controls, animation and a bounded SVG subset run locally, without model calls or a WebView. Both apps share the same runtime and HiDPI renderer. Images and arbitrary browser SVG are not supported.

Execution is opt-in and experimental: limits are cooperative in-process safeguards, not an OS sandbox. See the API and limitations.

Durable sessions (experimental)

Pi Desktop can also run sessions with a durable engine built on pi-durable. A session's state lives in SQLite on the computer that runs it, so the session survives disconnects and crashes and resumes where it was. Use it for SSH sessions (New session → SSH → Durable · experimental). Pi for Android always uses it: SSH sessions run durably on your computer; experimental Local sessions persist on the phone.

The macOS and Linux SSH helpers in the releases (pi-desktop-remote-*) have the engine built in. Local sessions don't need it; the steps above are enough. To build the engine into the helper yourself, on the machine that will run the sessions (it needs npm and Bun 1.4.3):

(cd backend/durable && npm ci --ignore-scripts && bun run build)
PI_DESKTOP_DURABLE_BINARY=$PWD/artifacts/durable/pi-desktop-durable \
  cargo build --release --locked -p pi_remote --features bundled-durable

To pair a phone with the computer, activate the helper first (turn on SSH first; on a Mac, System Settings → General → Sharing → Remote Login), then run the stable command:

target/release/pi-desktop-remote activate
~/.pi/desktop/bin/pi-desktop-remote pair

Activation keeps the executable under ~/.pi/desktop/bin/<sha256>/ and atomically selects it with the stable ~/.pi/desktop/bin/pi-desktop-remote symlink.

In the Android app, tap Scan computer QR and scan the code in the terminal. Check that both devices show the same six-digit code, then press Enter on the computer. Pairing goes through the computer's own SSH server and installs a phone key restricted to the helper; the helper can edit files and open a shell as that account. If the phone can't reach the address it found, add --host <address>; a Tailscale name or an IP works. The QR expires after two minutes (--expires <seconds> changes that). See Pi for Android for manual SSH-key setup.

See docs/remote.md for what it supports and how to install the helper, and backend/durable for its tests.

Scheduled jobs (experimental)

On Android, open Schedules on the computer’s Home screen to create recurring prompts, preview their cron/timezone, pause future runs and inspect each occurrence as a normal durable session. Enabling and Run now require explicit confirmation: Pi can execute commands and change files with your host account’s permissions.

Scheduling runs on the Linux or macOS computer, not on the phone. Use an updated durable-enabled helper, then explicitly start its scheduler locally:

~/.pi/desktop/bin/pi-desktop-remote scheduler start
# Optional: opt in to login autostart; installation does not start it immediately.
~/.pi/desktop/bin/pi-desktop-remote scheduler install --confirm

The computer must be awake. Defaults are fresh sessions, no same-job overlap and skipped missed times. Pausing/deleting a schedule keeps existing sessions. Windows durable scheduling is unsupported. See host setup, recovery and limitations and the Android guide.

Test

cargo test --locked --workspace

See docs/validation.md for the full checks and docs/architecture.md for how it works, including packaging.

Keys

Keys Action
Ctrl/Cmd+N New session
Ctrl/Cmd+O Open folder
Ctrl/Cmd+K Search
Ctrl/Cmd+B Sidebar
Ctrl/Cmd+J Terminal
Enter Send, or steer the current run while pi works
Alt/Option+Enter Queue a follow-up
Ctrl/Cmd+Enter Steer the current run
Escape Stop

License

GPL-3.0-or-later (LICENSE), because the app links Zed's GPL crates. Third-party notices are in THIRD_PARTY.md and licenses/.

About

Pi Gui

Resources

Stars

15 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages