Quick start

Requirements

• Rust stable (1.85+)
• Node.js 22+ (for building the UI, desktop packaging and the bundled pi runtime)
• pi coding agent installed or ready to use

Run from source

cd ui
npm install
npm run build
cd ..

cargo build --release
./target/release/pi-star --port 30151

Open http://127.0.0.1:30151.

Release builds embed ui/dist in the binary, so the binary can be copied to a directory without ui/dist. Debug builds read the repository’s ui/dist; rebuild the UI with npm run build without recompiling Rust.

Desktop app

Download the Linux, macOS or Windows package from Releases. The desktop installer bundles Node, pi and the agent extension, so those runtimes do not need to be installed separately.

The desktop shell handles launch, health checks, restart with backoff, tray, login item and process-tree cleanup. The main window is the local service’s web UI.

Development

# Terminal 1: Rust service (30151)
cargo run -p pi-star

# Terminal 2: Vite (30152, /api proxied to 30151)
cd ui && npm run dev

Data locations

pi-star does not invent a new session format; it uses pi’s data directory by default:

• Sessions: ~/.pi/agent/sessions/<encoded-cwd>/*.jsonl
• Settings: ~/.pi/agent/settings.json, models.json, auth.json
• Sidebar state: ~/.pi/agent/pi-web-session-state.json

Use --agent-dir or PI_CODING_AGENT_DIR to point at another data directory.