Modern Desktop Workbench for Local Grok Build CLI
Multi-Project Spaces · Real-time Agent Streaming · Integrated File & Code Loop · Omnichannel Remote IM · Desktop Companion & Personalization
Note
About Grok App: Grok App is an open-source desktop client and workbench for the local Grok Build CLI (grok agent stdio). It is not an official xAI product. The application does not bundle proprietary model backends; all chat reasoning, tool execution, and permissions run directly through your installed grok CLI.
Full agent capabilities require an installed and signed-in Grok Build CLI. The first-run setup wizard can assist with CLI installation, and UI-only development can be run with GROK_APP_ACP=mock.
- ✨ Key Highlights
- 🛠️ Features Overview
- 📸 Screenshots
- 🚀 Quick Start & Installation
- 💡 Platform Notes & Troubleshooting
- 📂 Configuration & Data Paths
- 💻 Building from Source & Development
- 🤝 Community & Contributing
- 👥 Contributors
- 📄 License & Author
- ⚡ Native Build Sessions — Deep integration with
grok agent stdiovia the ACP protocol. Granular permission tiers (Ask, Allow Once, Allow for Session, and YOLO mode) with Grok 4.6 Extra High (xhigh) enabled by default. - 🗂️ Multi-Project Workbench — Isolated project workspaces, agent status Kanban, one-click Git Worktree switching, session forking from any assistant reply, and cross-session context attachment.
- 📝 Files & Creation Loop — Embedded CodeMirror 6 editor with instant disk synchronization, visual Git Diff review, comprehensive media preview (images, video, audio, PDF, Office documents), and AI image/video generation via Imagine.
- 📲 Omnichannel Remote IM — Unified bridge connecting your local agent to Feishu/Lark, Telegram, Discord, Slack, DingTalk, WeCom, WeChat personal, QQ, Matrix, LINE, and Weibo; token-gated mobile web mirror and loopback REST session API.
- 🐾 Desktop Companion & Status Feedback — Interactive always-on-top desktop pet companion with live agent status awareness, responsive reactions, and notification bubbles.
- 🔐 Privacy & Custom Relays — API keys securely stored in your OS keychain. SuperGrok quota bar and heatmap tracking, custom provider relays (OpenRouter, DeepSeek, AI98PRO, etc.), and 15 built-in UI languages.
- Projects & Workspaces: Folder trust system, workspace isolation, virtualized high-performance sidebar, chat archiving, cross-project migration, and CLI session import.
- Parallel Workflows: Multi-session concurrent execution with continuous background streaming; intelligent process management and idle resource recycling; Kanban board (Needs Input / Working / Done).
- Git Worktree Integration: Automatically discovers linked Git worktrees for seamless working directory switching within sessions.
- Session Forking & Attachment: Branch off from any assistant turn with aligned context history; attach up to 3 reference sessions via
/attach-chator drag-and-drop.
- Structured Timeline: Thought reasoning, tool executions, and final responses streamed in real-time order with live activity indicators.
- Power Composer: Queue follow-up prompts while the agent is busy;
Ctrl+Enterto steer the active turn; type-to-focus; prompt history; selection quotes and inline annotations. - Granular Permissions: Interactive Ask confirmation by default; allow once, allow for session, per-project defaults, or unattended YOLO mode; workspace sandbox support.
- Plan & Goal Tracking: Sticky multi-step plan progress with full Markdown execution details and structured milestones in the resources panel.
- In-App Code & Text Editor: CodeMirror 6 multi-tab editor with live two-way file synchronization and instant disk reload after agent modifications.
- Visual Changes & Diffs: Inspect session modifications and workspace Git diffs with granular single-file or batch accept/reject/revert controls.
- Rich Media Viewer: Native rendering and preview for images, video, audio, PDF, and Word/Excel/PowerPoint documents; high-quality share-card image export.
- AI Asset Generation: Generate images and videos directly from the composer using the Imagine skill; integrated side-browser with Design Mode for local web development previews.
- Slash Commands & Skills: Fully aligned with Grok Build slash command palette, inline skill chips, and custom automated workflows (
/workflow). - Extensions Hub: Manage Model Context Protocol (MCP) servers, plugins catalog (OpenAI plugin compatible), skills, agents, and hooks with full user control.
- ChatCut Integration: Native integration for the recommended Codex plugin with automated OAuth refresh and external editor workflows.
- Scheduled Automations: Schedule recurring or one-off tasks with natural-language prompt creation and visual execution logs.
- 11+ IM Channel Bridges: Connect to your preferred messaging apps to monitor, resume, and steer your local desktop agent on the go (
/pproject switch,/rresume). - Mobile Web Mirror: Lightweight token-gated web app for mobile browsers; compatible with Cloudflare Quick Tunnel for secure remote access.
- Local Session API: Loopback REST endpoints (
GET /v1/sessions,POST /v1/sessions/{id}/turns) for scripting, CI, or third-party tool integrations.
- Multi-Account & Quota Tracking: Instant account switcher, official login, SuperGrok quota progress bar, cost heatmaps, and local tracking for custom providers.
- Flexible Relay Modes: Independent configuration mode or non-destructive shared mode (protects existing
~/.grokconfigurations); one-click presets for OpenRouter, DeepSeek, AI98PRO, etc. - Visual Customization: Light, dark, and system-adaptive themes; custom skins, wallpapers, UI fonts, terminal fonts, and share card styling.
- Internationalization: 15 built-in languages (EN, ZH, JA, KO, DE, FR, RU, ES, PT-BR, IT, ID, TA, UK, FIL, ZH-TW) with automatic OS locale detection.
| 🖥️ Workbench & Sessions | 📊 Account & Quota Heatmap |
|---|---|
 |
 |
| ☀️ Light Theme Mode | 💬 Media Preview & Interaction |
|---|---|
 |
 |
Download installers directly from the official website grok-app.com or GitHub Releases:
| Platform | Package Format | Details |
|---|---|---|
| macOS (Apple Silicon) | Grok_*_aarch64.dmg |
Apple Silicon (M1/M2/M3/M4) Macs |
| macOS (Intel) | Grok_*_x64.dmg |
Intel-based Macs |
| Windows (x64) | *-setup.exe / *-portable.zip |
Setup installer and portable archive |
| Linux (x64) | AppImage / .deb / .rpm |
Universal AppImage, Debian/Ubuntu, Fedora/RHEL |
💡 Note: The application bundle name is Grok. Prebuilt packages do not require Node.js, pnpm, or Rust installed on your system.
Each release includes a SHA256SUMS file. Verify your download with:
# macOS / Linux
shasum -a 256 -c SHA256SUMS --ignore-missing
# Windows (PowerShell)
Get-FileHash .\Grok_*_x64-setup.exe -Algorithm SHA256- Launch: Open Grok App. The setup wizard will automatically verify that the Grok Build CLI is installed (with multi-mirror fast install support).
- Account / Relays (Optional): Sign in with your official account, provide an API key, or configure a custom relay. If your local
grokCLI is already authenticated, simply choose Use existing CLI sign-in. - Add Project: Select and trust your project working directory.
- Connect Agent: Choose Ask or YOLO permission mode, and start building with your desktop agent!
- Local Grok Build CLI (
grok) 0.2.112 or newer (rungrok updatein terminal to upgrade). - Windows: Requires WebView2 Runtime (pre-installed on Windows 11; bootstrapped by the installer if missing).
In restricted network environments where Grok services cannot be reached directly:
- Navigate to Settings → Runtime → Network and configure your HTTP/SOCKS proxy (e.g.,
http://127.0.0.1:7890). - Click Test connection to verify connectivity to endpoints (
auth.x.ai,grok.com, etc.). The proxy is automatically injected into all agent processes.
Official releases starting from v0.2.19 are signed with an Apple Developer ID and Apple-notarized. If Gatekeeper blocks launching (e.g., on unsigned custom builds or due to quarantine metadata):
xattr -cr /Applications/Grok.app
open /Applications/Grok.appOr go to System Settings → Privacy & Security and click Open Anyway.
For unsigned community packages, Windows SmartScreen may display a warning on initial launch. Click More info → Run anyway. You can verify the file hash against SHA256SUMS for integrity.
On certain Wayland desktop setups (such as Hyprland with AMD GPUs), the universal AppImage may encounter rendering conflicts with the host Mesa/DRI stack:
- Recommended: Use system-integrated
.debor.rpmpackages which link against your distribution's native WebKitGTK. - When running the AppImage, you can try disabling hardware compositing:
WEBKIT_DISABLE_DMABUF_RENDERER=1 ./Grok_*.AppImageModern distributions such as Ubuntu 24.04+ restrict unprivileged user namespaces by default, which can prevent the bubblewrap agent sandbox from launching:
- Option 1 (Recommended, preserves sandbox isolation): Enable unprivileged user namespaces
sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
echo 'kernel.apparmor_restrict_unprivileged_userns=0' | sudo tee /etc/sysctl.d/99-userns.conf- Option 2: In Settings → Runtime → Sandbox, switch the sandbox mode to off.
Default application data directory (override via the GROK_APP_HOME environment variable):
| Operating System | Default Path |
|---|---|
| macOS | ~/Library/Application Support/com.grokapp.grok-app/ |
| Windows | %APPDATA%\grokapp\grok-app\ |
| Linux | ~/.grok-app/ |
Data layout:
<app-data>/
projects.json # Project registry
sessions_index.json # Session metadata index
settings.json # Application preferences
secrets.json # Secure key metadata (OS keychain prioritized, 0600 fallback)
automations.json # Scheduled automations
projects/ # Project-specific metadata
sessions/ # Persistent session history
logs/ # Diagnostic logs
agent-home/ # Independent mode GROK_HOME
To develop or build Grok App from source:
- Node.js:
v22.0.0or newer - pnpm:
v9.0.0or newer - Rust: Stable Toolchain
- Platform Build Tools: macOS Xcode CLT / Windows MSVC / Linux build-essential & webkit2gtk
# 1. Install dependencies
pnpm install
# 2. Start desktop development app (Tauri + Vite HMR)
pnpm dev
# 3. Start web frontend only (UI iteration)
pnpm dev:ui
# 4. Start with mock ACP backend (no CLI required)
GROK_APP_ACP=mock pnpm dev
# 5. Type checking and tests
pnpm typecheck && pnpm test
cd src-tauri && cargo test
# 6. Build production package
pnpm buildpnpm dev merges src-tauri/tauri.dev.conf.json (identifier com.grokapp.desktop.dev, product Grok Dev) so it can run beside installed Grok. Sessions still share App data unless GROK_APP_HOME is set. Bare tauri dev without --config uses the official identifier and will steal the installed instance.
Windows (optional): double-click install-latest.cmd to fast-forward origin/main and silently install an unsigned side-by-side grok-app-latest (does not replace official Grok). Needs VS Build Tools + Rust MSVC; details in docs/BUILD.md.
For cross-compilation and packaging instructions, see docs/BUILD.md.
Contributions, bug reports, and suggestions are warmly welcomed!
| Guide | Description |
|---|---|
| 📖 Agent & Product Rules | docs/llm-wiki/ |
| 🛠️ Build & Packaging Guide | docs/BUILD.md |
| 📝 Changelog | CHANGELOG.md |
| 💡 Contributing Guide | CONTRIBUTING.md |
| 🛡️ Code of Conduct | CODE_OF_CONDUCT.md |
| 🔒 Security Policy | SECURITY.md |
Thanks to everyone who has contributed to Grok App. All human GitHub contributors (by commit count, updated 2026-08-23).
This project is licensed under the MIT License.
| Channel | Link |
|---|---|
| 𝕏 X (Twitter) | @cgnot996 (铁柱AGI) |
| 📢 WeChat Official Account | Search 「铁柱AGI」 or scan top-left QR |
| 💬 WeChat Community | Scan top-right QR code |
| 🐧 Linux.do Community | linux.do — Learn AI on L-Station |
⭐ If Grok App empowers your daily workflow, please consider starring the repository!