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](https://x.ai) 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](#-key-highlights)
- [🛠️ Features Overview](#️-features-overview)
- [📸 Screenshots](#-screenshots)
- [🚀 Quick Start & Installation](#-quick-start--installation)
- [💡 Platform Notes & Troubleshooting](#-platform-notes--troubleshooting)
- [📂 Configuration & Data Paths](#-configuration--data-paths)
- [💻 Building from Source & Development](#-building-from-source--development)
- [🤝 Community & Contributing](#-community--contributing)
- [👥 Contributors](#-contributors)
- [📄 License & Author](#-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.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.
---
## 🛠️ 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, 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
| 🖥️ Workbench & Sessions | 📊 Account & Quota Heatmap |
|:---:|:---:|
|  |  |
| ☀️ Light Theme Mode | 💬 Media Preview & Interaction |
|:---:|:---:|
|  |  |
---
## 🚀 Quick Start & Installation
### 1. Download Prebuilt Packages
Download installers directly from the official website [grok-app.com](https://grok-app.com) or [GitHub Releases](https://github.com/RongleCat/grok-app/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.
#### Checksum Verification
Each release includes a `SHA256SUMS` file. Verify your download with:
```bash
# 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](#linux-runtime-libraries-appimage).
#### 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):
```bash
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.
---
### 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:
```text
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`):
```bash
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](#linux-display-notes-webkitgtk--wayland). See issue [#899](https://github.com/RongleCat/grok-app/issues/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](#linux-runtime-libraries-appimage).
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:
```bash
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
```bash
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):
| Operating System | Default Path |
|:---|:---|
| **macOS** | `~/Library/Application Support/com.grokapp.grok-app/` |
| **Windows** | `%APPDATA%\grokapp\grok-app\` |
| **Linux** | `~/.grok-app/` |
Data layout:
```text
/
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
```bash
# 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`](./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](./docs/BUILD.md).
For cross-compilation and packaging instructions, see [docs/BUILD.md](./docs/BUILD.md).
---
## 🤝 Community & Contributing
Contributions, bug reports, and suggestions are warmly welcomed!
| Guide | Description |
|:---|:---|
| 📖 **Agent & Product Rules** | [`docs/llm-wiki/`](./docs/llm-wiki/) |
| 🛠️ **Build & Packaging Guide** | [docs/BUILD.md](./docs/BUILD.md) |
| 📝 **Changelog** | [CHANGELOG.md](./CHANGELOG.md) |
| 💡 **Contributing Guide** | [CONTRIBUTING.md](./CONTRIBUTING.md) |
| 🛡️ **Code of Conduct** | [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) |
| 🔒 **Security Policy** | [SECURITY.md](./SECURITY.md) |
---
## 👥 Contributors
Thanks to everyone who has contributed to Grok App. All human GitHub contributors (by commit count, updated 2026-09-06).
[Full contributors graph →](https://github.com/RongleCat/grok-app/graphs/contributors)
---
## 📄 License & Author
This project is licensed under the [MIT License](./LICENSE).
### Connect with the Author & Community
| Channel | Link |
|:---|:---|
| 𝕏 **X (Twitter)** | [@cgnot996 (铁柱AGI)](https://x.com/cgnot996) |
| 📢 **WeChat Official Account** | Search **「铁柱AGI」** or scan top-left QR |
| 💬 **WeChat Community** | Scan top-right QR code |
| 🐧 **Linux.do Community** | [linux.do](https://linux.do/) — Learn AI on L-Station |
⭐ **If Grok App empowers your daily workflow, please consider starring the repository!**