Grok Build Desktop

English | 简体中文

Electron desktop client for Grok Build — a Claude Desktop–style shell over the same Rust agent your CLI uses.

Electron UI  →  ACP / JSON-RPC  →  grok agent serve  (loopback WebSocket)

Sessions, auth, and config live under ~/.grok and stay compatible with the Grok CLI / TUI.

Full app window: session sidebar, chat timeline, optional file preview column, and composer.

Full inventory: docs/FEATURES.md.

• Attach to an external live TUI / leader-socket session
• Bundled installers with embedded grok binary
• Auto-update, code signing
• Full command palette (Ctrl+K), /rewind

┌─────────────────────────────────────────────────────────────┐
│  Electron Main                                              │
│  · Resolve grok binary · Spawn agent serve · ACP client     │
│  · IPC whitelist · Kill child on quit                       │
└────────────────────────────┬────────────────────────────────┘
                             │ contextBridge (preload)
┌────────────────────────────▼────────────────────────────────┐
│  Renderer (React + Vite)                                    │
│  · Sessions · Timeline · Composer · Files · Settings · Ext  │
└────────────────────────────┬────────────────────────────────┘
                             │ WebSocket + JSON-RPC (ACP)
                             ▼
                    grok agent serve
                    127.0.0.1 only + random secret

Desktop does not rewrite the agent: one local serve process, multiple sessions can prompt concurrently; switching focus parks UI state without cancelling background turns.

• Node.js 20+
• Working Grok CLI (grok) and login (grok login)
• Binary resolution order:
  1. GROK_BINARY environment variable
  2. ~/.grok/bin/grok
  3. Packaged resources/bin/grok (reserved, not shipped yet)
  4. grok on PATH

cd ~/Projects/grok-build-desktop
pnpm install    # or: npm install
pnpm dev        # or: npm run dev

1. Open workspace and choose a project folder.
2. Wait until status is Ready.
3. Send a message — or resume a session from the sidebar.

electron-builder.yml defines the full set of release targets. A Vite production build runs first, then electron-builder produces per-platform artifacts under dist/.

Artifacts are named Grok Build Desktop-0.1.0-<arch>.<ext> and land in dist/ (or dist_<arch>/ if you set CSC_IDENTITY_AUTO_DISCOVERY=false).

• Linux — .deb targets Debian / Ubuntu, .rpm targets Fedora / RHEL / openSUSE. Post-install hooks (resources/scripts/) refresh the desktop / MIME / icon caches so the launcher appears immediately.
• macOS — Builds run only on macOS. Replace resources/icon.icns with your artwork; entitlements live in resources/macos/entitlements.plist. Signing and notarization are still TODO.
• Windows — Builds run only on Windows (or under Wine). Replace resources/icon.ico with multi-resolution artwork. NSIS gives a normal installer; the portable target produces a self-extracting .exe that runs without installation.

Full release CI and the bundled grok binary are still TODO.

• Agent binds 127.0.0.1 only, with a random per-process secret.
• Renderer: no Node integration; contextIsolation + fixed IPC whitelist.
• Closing the app stops the child grok agent serve process.
• Auth stays in CLI-compatible ~/.grok (desktop API key file uses mode 0600).

grok-build-desktop/
├── docs/
│   ├── DESIGN.md
│   ├── FEATURES.md
│   └── screenshots/          ← screenshot.png
├── src/
│   ├── main/                 ← Electron main, agent, FS, account
│   ├── preload/
│   ├── renderer/             ← React UI
│   └── shared/               ← ACP client + types
├── scripts/
├── package.json
├── README.md                 ← this file (English)
└── README.zh-CN.md           ← 简体中文

• Keep docs/FEATURES.md in sync when you ship or drop a capability.
• Architecture and protocol details live in docs/DESIGN.md.
• Prefer small, focused PRs; match existing TypeScript / React style.

Private MVP shell around the Grok Build agent. Product name and branding follow xAI / Grok Build. See your org’s license for distribution rules.