A liquid-glass macOS desktop shell for the Grok CLI / Grok Build agent.
Gwork does not reimplement the agent. It drives your installed grok binary over ACP (grok agent stdio) and provides a Cursor-style UI: chat, project file tree, Monaco editor, diffs, skills, MCPs, and settings.
- Chat with Grok (Agent / Plan / Ask modes)
- Projects and session history from
~/.grok/sessions - IDE: file tree, Monaco editor (Python, R, JSON, YAML, …), Ask agent on selection
- Diffs panel for agent file edits
- Skills & Agents and MCPs management
- BYOM (bring your own model names + API keys in Settings)
- Liquid glass theme (opacity + hue sliders)
| Requirement | Notes |
|---|---|
| macOS | Primary target (Electron can run elsewhere) |
| Node.js 20+ | nodejs.org |
| Grok CLI | Installed and logged in |
Install / update Grok CLI (example):
curl -fsSL https://x.ai/cli/install.sh | bash
grok --version
# log in if needed — use your usual Grok CLI auth flowgit clone https://github.com/kcncell/Gwork.git
cd Gwork
npm install
npm run electron:devThat starts Vite + Electron. The main process spawns:
grok agent --model <model> stdio
and speaks JSON-RPC (Agent Client Protocol).
| Command | Description |
|---|---|
npm run electron:dev |
Dev app with hot reload (use this day to day) |
npm run build |
Production web + Electron main/preload bundles |
npm start |
build then launch Electron |
npm run pack |
Unpackaged .app folder under release/ |
npm run dist |
macOS DMG/zip (needs a proper app icon for best results) |
Nothing in this source tree is your personal Grok login, chat history, or BYOM keys. Those live outside the project:
| Data | Location (on each user’s machine) |
|---|---|
| Chat sessions | ~/.grok/sessions/ |
| BYOM API keys | ~/.gwork/byom-models.json |
| Speech models | ~/.gwork/models/ |
| Grok CLI auth | Grok CLI / system keychain |
.gitignore excludes node_modules, dist, dist-electron, release, .env*, logs.
Before you push to GitHub, always run:
git status
# ensure no .env, keys, or personal paths are stagedEach person who clones Gwork uses their own Grok login and (optionally) their own BYOM keys.
- Create an empty public (or private) repo on GitHub named e.g.
Gwork. - From this folder:
cd ~/GitHub/Gwork
git init
git add .
git commit -m "Initial public Gwork source"
git branch -M main
git remote add origin https://github.com/kcncell/Gwork.git
git push -u origin main- Others:
git clone https://github.com/kcncell/Gwork.git→npm install→npm run electron:dev.
(This repo is already on GitHub; step 2 is only if you’re setting up a new clone from scratch.)
npm run distArtifacts land in release/. That is a binary package, not your chat data.
(Notarization / a polished public/icon.icns may still be needed for Gatekeeper.)
┌─────────────────────────────────────┐
│ Gwork (Electron + React + Monaco) │
│ liquid-glass UI │
└──────────────┬──────────────────────┘
│ IPC
┌──────────────▼──────────────────────┐
│ Main process · GrokBridge │
│ JSON-RPC over stdio │
└──────────────┬──────────────────────┘
│
┌──────────────▼──────────────────────┐
│ grok agent stdio │
│ tools · MCP · skills · sessions │
└─────────────────────────────────────┘
| Path | Role |
|---|---|
electron/main.ts |
Window, IPC, permissions |
electron/grok-bridge.ts |
ACP client to grok agent stdio |
electron/byom-store.ts |
Local BYOM names/keys (~/.gwork) |
electron/fs-store.ts |
Project file read/write + notebooks |
src/App.tsx |
Shell state, layout modes |
src/components/* |
Chat, Sidebar, Settings, editor, … |
src/styles/global.css |
Glass theme |
MIT — see package.json ("license": "MIT").
| Issue | Try |
|---|---|
| App won’t connect | Is grok on your PATH? Run grok --version in Terminal. |
| Empty chat / no agent | Log in with the Grok CLI first. |
| Monaco blank | Reopen the file; check toolbar language (python, r, …). |
| Port 5173 in use | Quit other Vite/Electron Gwork instances and restart. |
Built for people who already use Grok CLI and want a desktop shell around it.