GrokBuild Desktop App

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

You can also install GrokBuild just to manage custom OpenAI-compatible models in Settings → Models (writes ~/.grok/config.toml; no project or session needed), then use them in the grok TUI.

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 session (not needed if you only manage custom models)
• Tools the agent should find from the Dock (gh, Homebrew uv, …) on your login-shell PATH. GrokBuild merges that PATH at launch so Finder/menu-bar sessions see the same tools as Terminal. Set GROKBUILD_SKIP_SHELL_PATH=1 to leave PATH unchanged.

Quick Start

Start with a project

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 a session. GrokBuild Desktop App launches grok agent stdio for that project and streams it in the app.

Custom models only

If you mainly use the grok TUI or CLI and just need a UI for providers and models:

1. Install the grok CLI and open GrokBuild Desktop App (no project or grok login required for this path).
2. Open Settings → Models.
3. Install a provider (endpoint + API key), then add one or more OpenAI-compatible models.
4. Entries are written to ~/.grok/config.toml and work with the grok CLI/TUI via /model <id> — and in GrokBuild sessions if you use them later.

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. A common lightweight use is Settings → Models alone: manage custom providers and models for the shared ~/.grok/config.toml without opening a project or starting a session.

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

Sessions

• Streaming agent sessions for grok agent stdio with Markdown (headings — including numbered section titles in grok CLI blue — lists, tables, fenced code, and grok CLI–style colors, including replies that arrived as one smashed line), thinking blocks, CLI-style working lines (Read 1 skill, Listed 1 dir [hooks: 5] — search patterns and Computer Use calls stay as Searched / Computer Use, not raw grep), live tool cards, permission prompts, plan/question cards, and diff review. The agent shell runs in-app via ACP terminal/* (create / output / wait / kill / release). Protocol telemetry is not shown as assistant text. Scroll up to read earlier turns without being yanked; Jump to latest returns to the live end.
• Multi-tab sessions with lazy restore, resumable grok sessions, Sessions History (clock — resume/delete archived grok sessions), and transcript recovery from grok's on-disk chat_history.jsonl when possible.
• Visible session status on the sidebar — Working with elapsed time, Needs input, Completed, or Error — cleared when you focus the session, so parallel tabs show which one needs you.
• Session context menu — pin a session to the global Pinned section, settle finished work into a restorable shelf, mark unread/read, duplicate, clear the transcript, or close. Right-click a message to Rewind to Here (chat-only truncate; does not restore files).
• Steer mid-turn — send a prompt while grok is working to inject it into the running turn instead of queueing (grok never cancels the turn). Turn it on for every send with Settings → App → Steer by default, or pick Steer into current turn from the queue menu. Stop (⌘.) puts queued follow-ups back in the composer so they are not sent after the cancelled turn.
• Sound on finish — optionally chime when a turn ends and GrokBuild is not focused (Settings → App).
• Notify on finish — on by default. Posts a Notification Center banner when a turn ends and GrokBuild is not focused, and when a background session needs input (Settings → App to turn off). The banner uses the session and project names (redacted in Privacy Mode). Clicking it opens that session.
• Privacy Mode — redact project paths, project names, and session titles in the UI for screenshots (Settings → App). Stored data is unchanged.
• Composer controls for session agent/role, mode (Plan / Agent / Auto accept — approves tool cards, including ones already waiting; CLI id stays ), model, context usage (popover: window used/limit plus last-turn input / cached / output / reasoning when grok reports them), / , voice dictation, file attachments, slash-command autocomplete, (, , …), (, ), , with optional budget, prompt queue while streaming, (grid — this project’s live named sessions: needs you, failed, working, needs review, scheduled, idle), then (clock — this project’s archived grok sessions). , , and are all scoped to the current project.

Project Workflow

• Persistent sidebar with global agent/project/session search, pinned projects, a global Pinned session section, recent sessions, a collapsible Settled shelf, rename/close, and an Add Project plus in the Projects section header. Session titles skip injected prompt dumps (<user_info> / OS banners) and use the next real user line. Project folder path is a tooltip on the project name (hover), not a truncated second line.
• Per-tab model and per-project reasoning effort.
• Git branches and worktrees from the selected sidebar project’s branch chip (or Branches & Worktrees… on the project menu); New Worktree Session… on the project menu; WT badge on linked worktrees. The session dashboard Needs review group lists tabs with uncommitted changes; Preview opens the diff pane to apply, commit, or open a PR.
• Open in Finder, Cursor, VS Code, Terminal, iTerm, or Zed.

Custom models live in Settings → Models (~/.grok/config.toml). You can manage them with no project or session; they then work in the grok CLI/TUI and in GrokBuild.

• Listed A–Z by provider + model.
• Optional API backend (Chat Completions / Responses / Anthropic Messages) and env key so the secret stays out of the file. Do not reuse a built-in id such as grok-4.6 for a custom provider — that overrides native grok. GrokBuild prefixes colliding ids (for example acme-grok-4.6) and relocates existing shadows on launch.
• Create custom provider… includes an NVIDIA DGX Spark example (http://spark:8001/v1). Fetch models skips the key only for loopback URLs (localhost, 127.0.0.1, 0.0.0.0, host.docker.internal); LAN/Tailscale hosts need a dummy key such as not-needed.

Cursor models use a local OpenAI /v1 sidecar (not Compatibility → Cursor, and not the Computer Use Cursor MCP).

1. Settings → Models → Add Provider → Cursor, paste a Cursor API key, save.
2. The key is stored under Application Support (not Keychain, not config.toml). Models keep api_key = "local".
3. GrokBuild checks the key, then starts Node/@cursor/sdk on 127.0.0.1:18787. Cursor IDE need not be open. Needs system Node ≥ 22.13 (Doctor can install via Homebrew or nodejs.org).
4. Fetch models, then Add model (names like Cursor Composer 2.5). The local sidecar speaks OpenAI Chat Completions and Responses (POST /v1/responses) because grok 1.0.x uses Responses for Cursor Grok 4.6. Grok keeps its own tools; Cursor subscription/ToS is yours.

On a corporate TLS proxy (Zscaler), Node does not use the macOS keychain. If ~/IT-Certs/package-route.pem or GROKBUILD_NODE_EXTRA_CA_CERTS is set, GrokBuild passes it as NODE_EXTRA_CA_CERTS so Add Provider works from the Dock the same as from Terminal. Other Macs are unchanged.

Doctor (Settings → App → Open Doctor…) checks the grok CLI, auth, config.toml, login-shell PATH, Browser/Computer Use, Node.js, and (optionally) whether the Cursor bridge is reachable, with shortcuts to install the CLI, run grok login, or install Node.

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 composer agent/role pill (first in the composer row, before mode and model). Its Run this session as menu separates discovered agents from custom roles and makes clear that choosing a role runs the whole session rather than spawning a subagent. These choices pass through as grok --agent and restart the affected session.
• Agents — a global Agents section above Projects in the sidebar, with a New Agent plus in its header. The list defaults to active Agents (pinned, or with a live session in the current project); use Show all agents to see the rest. Add sample agents (Chief, Scout, Builder, Verifier, Operator) or create your own with a name, instructions, glyph, and color. Pin / Unpin keeps an Agent in the active list. Click an Agent to focus its live session in the current project or start a new one; bound sessions keep that identity in the session list, dashboard, and composer pill after restart. Deleting asks for confirmation, removes the roster identity, and leaves linked roles and existing sessions intact. Manage Agents from the sidebar (not Settings).
• 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. Saving an Agent also updates that linked role prompt. Deleting a role from Settings → Agents asks for confirmation before removing its table and managed prompt file; existing sessions stay.
• Using subagents — keep the main agent as Default and prompt 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"). Custom roles in the session-role picker run 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.

Why use Agents?

Agents turn recurring work styles into durable, recognizable shortcuts instead of making you restate instructions for every session:

• Consistent specialization — save instructions once for roles such as research, implementation, review, or operations.
• Faster project switching — click an Agent to focus its live session in the current project or start a correctly configured one.
• Persistent identity — the Agent name and glyph stay attached to its session across restore and duplication, and appear in the sidebar, dashboard, and composer.
• Visible activity — quickly see which Agents are Working or Idle; pin important ones and keep the default list focused on active work.
• Reusable roles — the linked role can run the whole current session or be invoked by grok as a child subagent when requested.

The three concepts are intentionally separate:

• Agent — GrokBuild’s saved identity, instructions, appearance, and session shortcut.
• Session role — the grok --agent role used to run the entire current session.
• Subagent — a child worker that grok spawns during a turn; choosing a custom role in the composer does not spawn one.

Example workflow: use Chief to keep scope and coordinate, Scout to research, Builder to implement, and Verifier to independently review. They can run as separate visible sessions, or Chief can ask grok to delegate a focused task to one of their linked roles as a subagent.

Optional Automation

Enable Browser and Computer Use from Settings → Browser / Settings → Computer Use. The enable switches apply immediately and restart grok. Runtime or permission edits still use Apply and Restart.

• Browser control — two exclusive backends in Settings → Browser. GrokBuild isolated lets Grok drive Chromium via browser_* MCP tools backed by agent-browser (open URL, snapshot, list tabs, click/type) using a managed automation profile or Chrome/Brave/Edge/Arc over CDP. Official plugin installs grok plugin install browser-use --trust (needs uv) and drives your logged-in Chrome or Browser Use Cloud; GrokBuild does not inject grokbuild-browser while that plugin is loaded. grok.com / Imagine follow the active backend.
• 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 → Memory, then browse ~/.grok/memory/ and add "Remember" notes there. 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 and the session dashboard Scheduled group. New Automation on the dashboard creates a named session that repeats a prompt on a schedule (/loop) — for recurring checks, not a one-off chat. Schedules only fire while GrokBuild Desktop App is open and that session process is alive (sessions with live /loop tasks are kept out of LRU eviction; inactive tabs without schedules may still be stopped).
• 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 (, , ) to create, read, edit, and reformat Office files from paths in your workspace. Spreadsheet skills may need installed for some conversions.

App Experience

• Native Help menu with GrokBuild Help, Getting Started, Settings Guide, Models (custom providers, Fetch then Add, Cursor sidecar), Agents, Roles & Subagents, Sessions (Dashboard vs History), and Browser & Computer Use guides.
• 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. When an upgrade is waiting, click the main-window Updates Available banner or Upgrade Available… in the menu bar to open that panel. App updates are offered only for signed and notarized releases.
• Dark-mode-first SwiftUI design with accessibility labels for interactive status controls.

Permissions & Privacy

• Optional Privacy Mode (Settings → App) redacts project paths and names in the UI for screen sharing; it does not change stored sessions or CLI data.
• 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 defaults to a separate managed Chromium profile. The official browser-use plugin instead uses your real Chrome (logins included) or a cloud browser — pick one backend in Settings → Browser. If you attach GrokBuild isolated to an existing browser over CDP, Grok can interact with that window.
• Computer Use requires macOS Accessibility permission. Screenshots require Screen Recording and are optional. After a local make run ad-hoc rebuild, macOS may drop that trust; GrokBuild prompts once per new app signature, or re-add .build/GrokBuild.app in System Settings → Privacy & Security → Accessibility.
• 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.