Grok App

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

https://grok-app.com

English · 中文 · Русский

  

---

[!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.

---

Contents

• ✨ Key Highlights
• 🛠️ Features Overview
• 📸 Screenshots
• 🚀 Quick Start & Installation
• 💡 Platform Notes & Troubleshooting
• 📂 Configuration & Data Paths
• 💻 Building from Source & Development
• 🤝 Community & Contributing
• 👥 Contributors
• 📄 License & Author

---

✨ Key Highlights

• ⚡ Native Build Sessions — Deep integration with grok agent stdio via the ACP protocol. Granular permission tiers (Ask, Allow Once, Allow for Session, and YOLO mode) with Grok 4.7 Extra High (xhigh) enabled by default. Grok 4.7 Fast is also selectable.
• 🗂️ 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, Requesty, DeepSeek, AI98PRO, etc.), and 15 built-in UI languages.

---

🛠️ Features Overview

1. Modern Workbench & Session Management

• 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-chat or drag-and-drop.

2. Agent Interaction & Live Streaming

• 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+Enter to 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.

3. Files, Media & Creation Center

• 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.

4. Extensions, Plugins & Automations

• 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.

5. Remote Connectivity & Cross-Device Access

• 11+ IM Channel Bridges: Connect to your preferred messaging apps to monitor, resume, and steer your local desktop agent on the go (/p project switch, /r resume).
• 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.

6. Accounts, Relays & Personalization

• 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 ~/.grok configurations); one-click presets for OpenRouter, Requesty, 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.

---

📸 Screenshots

---

🚀 Quick Start & Installation

1. Download Prebuilt Packages

Download installers directly from the official website grok-app.com or GitHub Releases:

💡 Note: The application bundle name is Grok. Prebuilt packages do not require Node.js, pnpm, or Rust installed on your system.

Checksum Verification

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

---

2. First Run & Setup

1. Launch: Open Grok App. The setup wizard will automatically verify that the Grok Build CLI is installed (with multi-mirror fast install support).
2. Account / Relays (Optional): Sign in with your official account, provide an API key, or configure a custom relay. If your local grok CLI is already authenticated, simply choose Use existing CLI sign-in.
3. Add Project: Select and trust your project working directory.
4. Connect Agent: Choose Ask or YOLO permission mode, and start building with your desktop agent!

Requirements

• Local Grok Build CLI (grok) 0.2.112 or newer (run grok update in terminal to upgrade).
• Windows: Requires WebView2 Runtime (pre-installed on Windows 11; bootstrapped by the installer if missing).
• Linux AppImage: host libEGL.so.1 plus WebKitGTK 4.1 / Ayatana — see Linux runtime libraries.

Network & Proxy Configuration

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.

---

💡 Platform Notes & Troubleshooting

macOS Gatekeeper / "App is damaged"

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.app

Or go to System Settings → Privacy & Security and click Open Anyway.

---

Windows SmartScreen Notice

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.

Third-party antivirus (Kaspersky and similar) may also flag the unsigned Tauri app and bundled CLI as a heuristic threat. That is a false positive on community builds. Verify the installer hash, then exclude the install folder and the app data directory (often under %LOCALAPPDATA%). Signing with Authenticode is the long-term fix; the app cannot whitelist itself inside the antivirus.

---

Linux runtime libraries (AppImage)

The official AppImage does not bundle host EGL / WebKit / tray libraries. On a clean Debian / Ubuntu install the binary can exit immediately:

error while loading shared libraries: libEGL.so.1: cannot open shared object file

Install the runtime packages the .deb already expects, plus EGL/GLES (confirmed on Debian 13 (trixie) x86_64 with official Grok_0.2.26_amd64.AppImage):

sudo apt-get install -y libegl1 libgles2 libwebkit2gtk-4.1-0 libayatana-appindicator3-1

Then chmod +x and run the AppImage (or the extracted usr/bin/grok-app). The .deb already lists libwebkit2gtk-4.1-0 and libgtk-3-0.

This is a missing shared library at process start. It is not the Wayland black-window / EGL_BAD_PARAMETER case in Linux Display Notes. See issue #899.

---

Linux Display Notes (WebKitGTK / Wayland)

If the process never starts and you see libEGL.so.1: cannot open shared object file, that is a missing host library — see Linux runtime libraries.

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 .deb or .rpm packages which link against your distribution's native WebKitGTK.
• The AppImage itself will use host WebKitGTK 4.1 when that package is installed (webkit2gtk-4.1 on Arch, libwebkit2gtk-4.1-0 on Debian/Ubuntu). That avoids the bundled-WebKit EGL_BAD_PARAMETER black window (#539) and SIGBUS in leftover WebKitNetworkProcess when the squashfs unmounts. Opt out with GROK_SKIP_SYSTEM_WEBKIT=1.
• When running the AppImage, you can try disabling hardware compositing:

WEBKIT_DISABLE_DMABUF_RENDERER=1 ./Grok_*.AppImage

• Do not wrap the AppImage with --appimage-mount and then kill the mount while WebKit helpers are still running — that is the SIGBUS path. Prefer this script, which extracts to a real directory: scripts/run-linux-appimage-system-webkit.sh.

---

Linux Workspace Sandbox (Ubuntu 24.04+)

Modern 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.

---

📂 Configuration & Data Paths

Default application data directory (override via the GROK_APP_HOME environment variable):

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

---

💻 Building from Source & Development

To develop or build Grok App from source:

Prerequisites

• Node.js: v22.0.0 or newer
• pnpm: v9.0.0 or newer
• Rust: Stable Toolchain
• Platform Build Tools: macOS Xcode CLT / Windows MSVC / Linux build-essential & webkit2gtk

Development Workflow

# 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 build

pnpm 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.

---

🤝 Community & Contributing

Contributions, bug reports, and suggestions are warmly welcomed!

---

👥 Contributors

Thanks to everyone who has contributed to Grok App. All human GitHub contributors (by commit count, updated 2026-10-11).

Full contributors graph →

---

📄 License & Author

This project is licensed under the MIT License.

Connect with the Author & Community

⭐ If Grok App empowers your daily workflow, please consider starring the repository!