GrokBuild Desktop App

GrokBuild Desktop App is a native SwiftUI macOS shell for the grok CLI — a project-focused chat UI with persistent workspaces, resumable sessions, and settings for CLI features.

Requirements

• macOS 26 (Tahoe) or later
• The grok CLI installed, usually at ~/.grok/bin/grok
• A logged-in CLI session — run grok login in Terminal before starting your first chat

Quick Start

1. Install and sign in to the grok CLI (grok login).
2. Download a notarized release from GitHub Releases and move GrokBuild.app to /Applications.
3. Open GrokBuild Desktop App and choose Add Project.
4. Pick a folder. It can be a code repo, a docs folder, or a scratch workspace.
5. Start chatting. GrokBuild Desktop App launches grok agent stdio for that project and streams the session in the app.

What GrokBuild Desktop App Is

GrokBuild Desktop App owns the macOS window, project sidebar, session tabs, settings UI, browser/computer-use enablement, and local app update flow.

It is not a replacement for the CLI. The grok CLI still owns agent reasoning, ACP, MCP tools, models, skills, subagents, plan mode, permissions, memory, hooks, plugins, and AGENTS.md instructions.

Install

Download a notarized release from the GitHub Releases page, then move GrokBuild.app to /Applications (or run it from the extracted folder). Releases are signed and notarized — no Gatekeeper workarounds needed.

Release assets are versioned, e.g. GrokBuild-v0.1.10.app.zip and GrokBuild-v0.1.10-macOS.dmg.

Feature Highlights

Core Chat

• Streaming chat for grok agent stdio with Markdown, thinking blocks, live tool cards, permission prompts, plan/question cards, and diff review.
• Multi-tab sessions with lazy restore, resumable grok sessions, a session browser, and transcript recovery from grok's on-disk chat_history.jsonl when possible.
• Composer controls for model, mode, context usage, voice dictation, file attachments, slash-command autocomplete, skill chips (/design, /review, …), research/workflow chips (/deep-research, /create-workflow), imagine chips, /goal with optional budget, prompt queue while streaming, and session dashboard.
• Guided empty state with quick-start prompts; use Clear on an Empty session to remove it from the tab strip.

Project Workflow

• Persistent project sidebar with pinned projects, recent sessions, session rename/close, and one-click Add Project onboarding.
• Per-tab model selection and per-project reasoning effort.
• Git branch/worktree management from the chat status row.
• Open in menu for Finder, Cursor, VS Code, Terminal, iTerm, and Zed.
• Custom OpenAI-compatible models and reusable providers written to ~/.grok/config.toml.

Agent Capabilities

• Main agents — browse agents discovered by grok inspect --json, choose the default agent for new sessions, or override the active tab from the chat agent pill. These choices pass through as grok --agent and restart the affected session.
• Custom subagents (roles) — create reusable roles with a name, optional model, and instruction. GrokBuild Desktop App writes them to [subagents.roles.*] in ~/.grok/config.toml and stores instructions in ~/.grok/prompts/<name>.md.
• Using subagents — keep the main agent as Default and chat normally; grok delegates to matching subagents automatically, or you can ask for one by name (for example, "use the researcher subagent to map the auth flow"). Run as custom role in the agent picker runs the whole session as that role instead of spawning a child subagent. To block spawning child subagents, use Settings → Permissions.
• Inspect hooks, plugins, marketplace sources (install/enable/disable), compatibility layers (Cursor/Claude/Codex), skills, MCP servers, and session permissions from Settings.

Optional Automation

Enable Browser and Computer Use from Settings → Browser / Settings → Computer Use, then Apply and Restart, or use the matching status-bar pills when a session is active.

• Browser control — let Grok drive a real Chromium browser via browser_* MCP tools backed by agent-browser. Use a managed automation profile or attach to Chrome, Brave, Edge, Arc, or another Chromium browser over CDP.
• Computer Use — let Grok drive native macOS UI via computer_* MCP tools backed by agent-desktop, with action policy, step limits, timeouts, and optional Cursor MCP integration.
• Memory — experimental and off by default. Enable from Settings, browse ~/.grok/memory/, and add "Remember" notes from the chat status bar. Slash commands like /flush and /dream remain TUI-only.
• Background tasks — scheduled /loop tasks plus background shells, monitors, and subagents mirrored in the Tasks pill. Schedules only fire while GrokBuild Desktop App is open and that session process is alive (inactive tabs may be stopped by LRU eviction).
• Rhai workflows — enable in Settings → Workflows ([workflows] enabled in config.toml, shared with the grok TUI). The Workflows pill lists runs, saved .grok/workflows/ scripts, and deep research. This is separate from skill chips in the composer.
• Session tools — fork session (new tab with --fork-session), share link (/share + clipboard), /btw aside panel, create-skill sheet, and multi-session dashboard grouped by status.
• Documents and spreadsheets — use grok's document skills (xlsx, docx, pptx) to create, read, edit, and reformat Office files from paths in your workspace. Spreadsheet skills may need LibreOffice installed for some conversions.

App Experience

• Menu bar item plus main window with status-dot icon, quick actions, settings, update checks, and sign-in recovery.
• In-app update panels for both GrokBuild Desktop App and the grok CLI. App updates are offered only for signed and notarized releases.
• Dark-mode-first SwiftUI design with accessibility labels for interactive status controls.

Permissions & Privacy

• GrokBuild Desktop App talks to the local grok CLI; your prompts, tool calls, model routing, auth, and CLI-side storage follow the CLI's behavior.
• Browser control uses a separate managed Chromium profile by default. If you attach to an existing browser over CDP, Grok can interact with that browser window.
• Computer Use requires macOS Accessibility permission. Screenshots require Screen Recording and are optional.
• You can control tool approval behavior in Settings → Permissions and Settings → Computer Use (Auto / Ask / Deny, plus limits).

Building from source

Minimal setup

You only need Xcode Command Line Tools:

xcode-select --install

That is enough to compile the app, create the .app bundle and DMG, and codesign/notarize.

make build          # build the release binary
make test           # run unit tests
make run            # build release + launch from .build/GrokBuild.app
make run-debug      # build debug + launch — includes menu **Simulate Updates**
make app            # create dist/GrokBuild.app
make dmg            # create the .app + DMG

See BUILDING.md for packaging, signing, notarization, and GitHub releases.

Opening a self-built (unsigned) app

Local builds from make app / make run are unsigned. macOS Gatekeeper may block them the first time you open a copied .app (for example after moving dist/GrokBuild.app to /Applications):

1. Right-click GrokBuild.app → Open, then confirm Open (bypasses the block once).
2. Open System Settings → Privacy & Security and click Open Anyway next to the blocked-app message.
3. Or remove the quarantine attribute:

   xattr -cr /path/to/GrokBuild.app

Self-built apps do not receive in-app upgrade offers. Use a notarized GitHub release for one-click updates, or keep rebuilding from source.

Recommended for SwiftUI work

If you plan to edit the SwiftUI code, install the full Xcode IDE from the App Store for:

• SwiftUI Previews (live canvas) — the biggest advantage
• Better debugging tools (view hierarchy, environment inspection)
• A smoother experience with complex SwiftUI views

You can still build from the terminal with make or swift build with full Xcode installed:

xed .          # open Package.swift in Xcode

Signing & notarization

cp .env.example .env   # optional: SIGN_IDENTITY, NOTARY_PROFILE
make signed SIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)"
make notarize NOTARY_PROFILE=AC_PASSWORD
make release RELEASE_TYPE=notarized

Signing requires a Developer ID Application certificate, and notarization requires App Store Connect access. Full details: BUILDING.md.

Developer documentation

Doc	Purpose
ARCHITECTURE.md	Start here — app structure, data flow, persistence, updates, common tasks → files
AGENTS.md	Agent/copilot entry point
BUILDING.md	Build, sign, notarize, release CI

Debug builds (make run-debug) include a menu-bar Simulate Updates submenu for testing the update UI without publishing releases. It is compiled out of release builds (make run, make app, GitHub releases).

License

Apache License 2.0. GrokBuild Desktop App is an independent desktop client for the Grok Build CLI and is not affiliated with, endorsed by, or sponsored by xAI.