Architecture

Components

ui/                     Vite adaptation of pi-web's UI (React 19 + Tailwind 4)
crates/pi-star-ai/      Models, providers, streaming protocols and usage
crates/pi-star-agent/   Agent loop, events, queues and tool calls
crates/pi-star-tools/   Built-in tools and ExecutionEnv
crates/pi-star-harness/ Session state machine, compaction, prompt, skills
crates/pi-star-core/    Sessions, config, models, files/Git, terminal, UiState
crates/pi-star/         Axum routes, SSE, assets, auth and CLI
app/                    Tauri 2 desktop shell (separate workspace)

Release builds embed the UI in the pi-star binary and serve it through Axum; the server needs no Node runtime. Debug builds still read the UI from disk for frontend iteration.

Data boundary

pi-star keeps using pi’s ~/.pi/agent data: JSONL sessions, settings.json, models.json, auth.json and pi-web sidebar state. After pi-star stops, the pi CLI or pi-web can continue the same sessions.

Agent backends

id	Name	Implementation
rpc	Standard PI	pi --mode rpc subprocess, TypeScript extensions supported
quick	QuickPI	In-process AgentHarness

The backend is stored in the session file’s pi-star:agent-backend custom entry and travels with the session. Without that entry, standard PI is used. A session can only be written by one backend at a time.

Desktop shell

app/ is a separate Tauri 2 workspace that only:

• starts one instance and locates the bundled pi-star
• confirms process ownership through stdout lifecycle events and /api/health
• supervises crashes and restarts with backoff
• provides splash/error pages, tray, launch at login and close-to-tray
• cleans up the pi-star, Node and PTY process tree on exit

The main window has no Tauri IPC permissions; only the local splash page can retry, quit or open logs.

Local first

pi-star binds to the local machine by default, and local configuration decides authentication and access. It does not depend on QuadHub; QuadHub Token is an optional model-service integration.