Prime Desktop

A cross-platform (Windows / Linux) desktop GUI for prime-agent. Chat with your agent, run parallel bot teams, browse the workspace, and open a live terminal — all in one native app.

The prime-agent SDK runs inside the Electron main process — no daemon socket handling, identical behavior on Windows and Linux. Your existing ~/.prime/agent config, auth, and session history are used as-is.

Features

• Chat with streaming responses — markdown, syntax-highlighted code blocks, live thinking stream
• Live tool-call cards — see every command the agent runs and its output
• Bots (profiles) — named bots with their own model, thinking level, persona, color, and emoji. Mention them with @Name (autocomplete shows each bot's persona). Bots have full tools and share the working dir.
• Private DMs — the 💬 button on any bot opens a persistent 1:1 chat (own history, context replay across restarts, unread badge, 🧠 reset-memory and ↻ continue actions).
• Group chat — several bots discuss and work on the same project: ↻ Round takes turns, ⇉ Parallel runs all mentioned bots at once, and ✦ Synthesis merges the results.
• Bot templates — 7 preset personas (Reviewer, Tester, Docs, Security, PM, Architect, Coder) one click away in the editor; clone bots with ⧉.
• Bot import/export — share bot configs as JSON via Ctrl+K.
• Workspace dock (🗂 / Ctrl+B) — live file tree of the working directory with a preview pane: rendered markdown, syntax-styled code with copy buttons, and images. A Shell tab runs commands with live output, and bots with 🌿 worktrees expose their status and diff right in the panel.
• Git worktree isolation — enable "Own git worktree" on a bot and it works on its own branch (.pd-worktrees/<bot>, branch pd/<bot>), leaving the main tree untouched. Merge back with one click.
• Command palette (Ctrl+K) — fuzzy search across commands, bot mentions, recent sessions, and full-text transcript search.
• Session management — resume any past session, sort by date/name/project, group by project, pin, search.
• Conversation search (Ctrl+F) — highlight all matches with next/previous navigation.
• Usage meter — live input/output token and cost totals per session, with a context-pressure warning.
• Voice readout — optional TTS of assistant and bot replies.
• Image attachments — 📎 button or paste images into the composer; vision-capable models can see them.
• Chat export — export the current session or group chat as markdown.
• Keyboard shortcuts — Ctrl+K palette, Ctrl+F search, Ctrl+N new chat, Ctrl+G group chat, Ctrl+B dock, Ctrl+S export, ? cheat-sheet, Esc stop/close.
• Model picker — all configured providers and thinking-level selector.
• Working-directory picker — set the per-window agent cwd; bots rebuild against it.
• Light/dark theme, zoom (Ctrl+=/-/0), and a welcome tour on first run.

Requirements

• Node.js 20+ and npm
• A working prime-agent installation (auth via the prime-agent CLI or ~/.prime/agent/auth.json). The agent can be installed globally (npm i -g prime-agent) or as the local @earendil-works/pi-coding-agent package.
• Windows only: bash.exe on PATH (Cygwin/MSYS2/WSL) — required by prime-agent's shell tools.

Install

One-command installer (recommended)

Clone the repo (or download and extract), then run the installer:

git clone https://github.com/spfcraze/Prime-Desktop.git
cd Prime-Desktop
bash install.sh

install.sh will:

1. Check for Node.js 20+ and npm.
2. Detect your existing prime-agent install (from PRIME_DESKTOP_SDK, a global prime-agent/@earendil-works/pi-coding-agent, or a local @earendil-works/pi-coding-agent) and tell you which one it found.
3. Install dependencies and approve the Electron postinstall.
4. Launch the app.

If no prime-agent is detected, the installer prints exactly what to install and how — it will still open the app so you can set it up.

Manual install

npm install
npm start

If npm blocks install scripts, approve electron once:

npm install-scripts approve electron
node node_modules/electron/install.js

How it finds prime-agent

The SDK is resolved from, in order:

1. PRIME_DESKTOP_SDK env var (path or package name)
2. a global prime-agent install (npm root -g)
3. a local @earendil-works/pi-coding-agent install

The app uses your existing auth, model registry, and sessions — no reconfiguration needed. If it can't find a compatible SDK, it shows a clear message naming each source it tried.

Optional environment variables

Variable	Purpose
PRIME_DESKTOP_CWD	initial working directory (default: home)
PRIME_DESKTOP_SDK	pin a specific prime-agent SDK path/package
PRIME_DESKTOP_LIVE_CAPTURE=<path>	write a PNG of the window ~1×/sec (for headless debug)
PRIME_DESKTOP_SHOT=<path>	capture a screenshot after startup and exit (debug)
PRIME_DESKTOP_INPUT_PORT=<port>	enable the token-gated remote input bridge (debug)

Headless live view

On machines without a working display (VMs, containers, broken compositors), watch the app live in your browser:

scripts/live-view.sh [port]   # default 8090

Open the printed URL from any device. The app self-captures its framebuffer ~1×/sec and streams it as MJPEG — no GPU, VNC, or compositor required. The page is also interactive: click, scroll, and type to control the app remotely. The input bridge is token-gated (a fresh secret per session, embedded only in the served page).

Packaging

npm run dist:linux   # AppImage + deb  (output in release/)
npm run dist:win     # NSIS installer  (build on Windows)

The packaged app still resolves the prime-agent SDK from the machine (global prime-agent, local @earendil-works/pi-coding-agent, or PRIME_DESKTOP_SDK) — install prime-agent alongside it.

Troubleshooting

• App opens but shows only a taskbar icon on Windows under WSLg. This is a WSLg shared-memory transport failure, not an app bug. Run wsl --shutdown from a Windows terminal, reopen WSL, and start the app again. See ARCHITECTURE.md / the WSLg notes for details.
• "Could not load a compatible prime-agent SDK": install prime-agent globally, install @earendil-works/pi-coding-agent locally, or set PRIME_DESKTOP_SDK.
• Windows shell tools don't work: make sure bash.exe (Cygwin/MSYS2/WSL) is on PATH.

License

MIT

Architecture

See ARCHITECTURE.md for the module layout, event flow, and how the SDK is embedded.