Pi Native

Codex-style desktop shell for the pi coding agent, built with Native SDK (no Electron).

Inspired by pi-gui: threaded session timeline, workspace sidebar, composer. This MVP drives the existing pi CLI and reads ~/.pi/agent/sessions/**/*.jsonl as the source of truth — it does not embed @earendil-works/pi-coding-agent.

Installation

Full guide (Linux, macOS, Windows): docs/INSTALL.md

One-key install

Installs into ~/.local/share/pi-native and puts a launcher in ~/.local/bin:

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/linuxing3/pi-native/main/scripts/install.sh | bash

# Windows
irm https://raw.githubusercontent.com/linuxing3/pi-native/main/scripts/install.ps1 | iex

Then run pi-native. Still need pi and python3 on PATH.

Pin a version with PI_NATIVE_VERSION=0.2.3 (bash) or $env:PI_NATIVE_VERSION = "0.2.3" (PowerShell).

Manual install (prebuilt)

1. Install pi and ensure python3 is on PATH.
2. Download the archive for your platform from Releases:

Platform	Artifact
Linux x64	pi-native-*-linux-x64.tar.gz
Linux arm64	pi-native-*-linux-arm64.tar.gz
macOS Apple Silicon	pi-native-*-macos-arm64.zip
Windows x64	pi-native-*-windows-x64.zip
Windows ARM64	pi-native-*-windows-arm64.zip

3. Extract into ~/.local/share/pi-native (keep bin/ + scripts/ together).
4. Run via ~/.local/bin/pi-native or set PI_NATIVE_ROOT and launch bin/pi-native (.exe on Windows).

Verify checksums with SHA256SUMS.txt from the same release.

Requirements

To run a release build

• pi on PATH
• Python 3 (python3 on PATH)
• Graphical session (Linux: DISPLAY / Wayland; Windows: WebView2; macOS: normal desktop)

To build from source

• Node.js 24+ (for native CLI / TypeScript check)
• Zig 0.16 (downloaded by native on first build)
• GTK4 + pkg-config + clang (Linux build)
• pi and Python 3 as above

UOS Desktop 20: stock GTK3 / glibc 2.28 cannot build Native SDK apps. Use the NixOS install on /mnt (or another GTK4 host).

Features

MVP

• List workspaces and sessions from ~/.pi/agent/sessions
• Timeline of user / assistant / tool rows from JSONL
• Composer: Send continues the selected session via pi -p --session …
• New session in the selected workspace cwd
• Cancel in-flight run; desktop notification when a run finishes

v0.2+

• Chat — bubbles + markdown/code; Enter sends, Shift+Enter newline.
• Worktrees — list/add git worktrees for the selected workspace cwd.
• Terminal — PTY shell (bash -l) with streamed mono output (full VT needs Ghostty opt-in).
• Diff — git diff with inline added/removed line washes.
• Agents — two concurrent pi slots (agent1 / agent2) over recent sessions.
• Settings — theme, plugins, account (API key write + logout against ~/.pi/agent/auth.json; OAuth still via pi → /login).
• Chrome — pi-web-inspired icon rail, session drawers, and default Pi Web paper palette (Settings → Theme).

After Msg/markup changes, rebuild before running zig-out/bin/pi-native (stale contracts cause unknown message tag). On UOS/older glibc hosts, launch via ./scripts/run-pi-native.sh so Nix GTK4/glibc match the binary.

A local Native SDK patch (patches/@native-sdk+cli+0.9.5-a11y-focus.patch) skips accessibility republish on app activate/deactivate-only focus flips (herdr/WM tab switches), which previously SEGV'd inside a11y hashing on Linux/GTK.

Building from source

NixOS on /mnt (from UOS)

export PI_NATIVE_ROOT=/share/data/sources/pi-native
sudo /share/data/sources/home-config/disko/nixos-enter-uos.sh --root /mnt \
  --command "bash $PI_NATIVE_ROOT/scripts/nixos-dev.sh"

One-shot check + release build (needs clang in the shell):

sudo /share/data/sources/home-config/disko/nixos-enter-uos.sh --root /mnt \
  --command "bash -lc 'export HOME=/home/Designers; nix-shell -I nixpkgs=flake:nixpkgs -p nodejs_24 gtk4 pkg-config clang --run \"bash $PI_NATIVE_ROOT/scripts/nixos-build.sh\"'"

Booted NixOS / GTK4 machine

cd /share/data/sources/pi-native
export PI_NATIVE_ROOT="$PWD"
./scripts/nixos-dev.sh

Set PI_NATIVE_ROOT and run from a session with a working DISPLAY (X11). The binary is zig-out/bin/pi-native.

Other hosts (Native SDK)

npm ci
bash scripts/apply-native-sdk-patches.sh
npx --no-install native check
npx --no-install native build --yes
# Windows CI uses -Dtarget=x86_64-windows-gnu
# Windows arm64 CI cross-builds -Dtarget=aarch64-windows-gnu from Linux aarch64
export PI_NATIVE_ROOT="$PWD"
./zig-out/bin/pi-native   # or zig-out/bin/pi-native.exe

Layout

Path	Role
src/core.ts	Model / Msg / update
src/app.native	UI markup
scripts/pi_bridge.py	JSONL ↔ tab-separated lines for the Native core
scripts/nixos-dev.sh	GTK4 nix-shell + stub-ld wrapper + native dev
scripts/nixos-build.sh	Same wrap + native check / native build
docs/INSTALL.md	End-user install for all release platforms
scripts/install.sh	One-key installer (Linux / macOS → ~/.local)
scripts/install.ps1	One-key installer (Windows → %USERPROFILE%\.local)

Releases

GitHub Actions builds Linux (x64 + arm64), macOS (arm64), and Windows (x64 + arm64) on every v* tag (and via Actions → Release → Run workflow).

Windows CI targets x86_64-windows-gnu (on windows-latest) and aarch64-windows-gnu (cross-built from ubuntu-24.04-arm; native windows-11-arm fails under that target). A small local patch to @native-sdk/cli skips the app-code object cache split (Zig COFF cannot merge the scriptc archive + multiple C++ hosts into one .obj) and defines NOMINMAX for the Windows hosts.

git tag v0.2.3
git push origin v0.2.3

Artifacts land on the GitHub Releases page with SHA256SUMS.txt. Install steps: docs/INSTALL.md.

CI

Pushes and PRs to main run native check on Ubuntu / macOS / Windows and build package artifacts for each platform.

Out of scope (for later)

Worktrees, PTY terminal, inline diffs, multi-agent orchestration, settings/OAuth UI are partly in v0.2; remaining polish (full VT, OAuth UI, etc.) still uses pi auth / existing ~/.pi/agent.