Skip to content

README.md

Latest commit

 

History

History
99 lines (68 loc) · 4.63 KB

README.md

File metadata and controls

99 lines (68 loc) · 4.63 KB
Raw

Korg Bro

A desktop client for Grok Build.
Same official grok CLI, login, and sessions — with a dedicated desktop UI.

MIT license Latest release CI status

Install · How it works · Build from source · Contributing

Korg Bro session and chat interface

Korg Bro is an unofficial desktop GUI client for Grok Build. It uses the official grok CLI, login, and sessions already in ~/.grok, so you can move between the CLI and Korg Bro without a separate account or session format.

Korg is Grok spelled backward. Add bro.

Highlights

  • Browse, search, resume, fork, and organize existing Grok sessions.
  • Follow responses, tool work, diffs, attachments, and queued follow-ups in one thread.
  • Switch models and permission modes, use voice input, and keep an eye on usage.
  • Manage Grok plugins, skills, hooks, and MCP servers from the desktop UI.

Install

Download the installer for your system from Releases. Choose the .dmg or .exe asset, not GitHub's auto-generated source archive.

Platform Installer
macOS, Apple Silicon Korg Bro_<version>_aarch64.dmg
macOS, Intel Korg Bro_<version>_x64.dmg
Windows, x64 Korg Bro_<version>_x64-setup.exe

Korg Bro requires macOS 11 or later, or Windows 10 version 1809 or later with WebView2. On macOS, open the DMG and drag Korg Bro into Applications.

Note

Windows builds are currently unsigned. If SmartScreen blocks the first launch, choose More info → Run anyway. If Defender quarantines the installer, restore it from Protection history.

You do not need to set up the CLI first. If grok is missing, Korg Bro runs xAI's official installer from x.ai on first launch, then opens the normal Grok sign-in flow.

How it works

React UI  →  Tauri host  →  one `grok agent --leader stdio`  →  Grok
                           ├─ read-only session journal → transcript history
                           └─ `~/.grok/korg` → Korg-only UI preferences

Grok remains the source of truth for sessions, authentication, billing, queues, plugins, skills, MCP servers, hooks, and trust. Korg Bro sends Grok-facing actions through ACP and presents the returned state.

Authentication stays inside Grok. Korg Bro does not read or write auth.json; session journals are read-only, while Korg-only preferences such as aliases, pins, and read markers live under ~/.grok/korg.

For contributor-level architecture and code boundaries, see CONTRIBUTING.md and CHEATSHEET.md.

Build from source

You need Node.js 22+, pnpm 10+, and Rust 1.80+.

git clone https://github.com/lynnzc/korg-bro.git
cd korg-bro
pnpm install
pnpm desktop:dev

The first Rust compile can take a while; later UI changes use Vite hot reload. To create a local installer, run pnpm desktop:build. A bare cargo build --release is not enough because that binary still expects the Vite development server.

Contributing

Bug reports and focused fixes are welcome. Please open an issue before starting a feature or architecture change, and read CONTRIBUTING.md for the project layout and required checks.

Security

Korg Bro can ask Grok to act on your local workspace, so only install builds you trust — the same standard you would apply to grok itself.

For vulnerabilities or leaked credentials, do not open a public issue. Follow the private reporting instructions in SECURITY.md.

License

Korg Bro is available under the MIT License. Maintained by Lynn.

Korg Bro is not affiliated with or endorsed by xAI. Grok, Grok Build, and Grok Bot are xAI products; all related names and trademarks belong to their respective owners.