Grok Build, made for Hyprland.
HyprGrok is a lightweight Hyprland companion for the official Grok Build grok CLI.
It does not call the xAI API and never stores API keys.
Authentication, models, and agent capabilities stay with official Grok Build.
HyprGrok only launches, resumes, and enhances real grok sessions with desktop awareness and a glass panel UI.
| Sessions | History |
|---|---|
![]() |
![]() |
| Control | Purpose |
|---|---|
| What you're focused on | Active app / folder from Hyprland (the panel itself is ignored) |
| Get quick answer | One-shot reply in the panel (grok -p) |
| Open full Grok session | Interactive TUI in your terminal |
| Analyze focused window | Auto-builds a rich prompt from the focused app |
| Sessions / History | Real data from ~/.grok/sessions + resume |
Default toggle: Super + Space
Running grok in a terminal works. HyprGrok adds what a tiling desktop users actually want:
- One keybind → polished floating panel
- Desktop context (window, project root, optional screenshot)
- Browse and resume real Grok Build sessions
- Status chip for Quickshell (Illogical Impulse) or Waybar
- Install / uninstall that is clearly marked and reversible
| Required | Optional |
|---|---|
| Hyprland | grim (screenshots) |
| Python 3.12+ | Chrome / Chromium / Firefox (panel UI) |
Official Grok Build (grok on PATH) |
kitty / foot / alacritty / … |
| Waybar or Quickshell (status bar) |
git clone https://github.com/dcbert/hyprgrok.git
cd hyprgrok
./install.shcurl -fsSL https://cdn.jsdelivr.net/gh/dcbert/hyprgrok@main/install.sh | bashPrefer jsDelivr over
raw.githubusercontent.com— GitHub’s raw CDN can lag after updates.
./install.sh --no-hyprland # skip keybinds / window rules
./install.sh --prefix ~/.local
./install.sh --force # overwrite ~/.config/hyprgrok/config.tomlPiped with flags:
curl -fsSL https://cdn.jsdelivr.net/gh/dcbert/hyprgrok@main/install.sh | bash -s -- --no-hyprlandThe installer will:
- Check for Python /
grok/ browser / Hyprland tools - Install to
~/.local/share/hyprgrok+~/.local/bin/hyprgrok - Create
~/.config/hyprgrok/config.toml - Append clearly marked Hyprland binds & rules (
BEGIN/END HYPRGROK) - Wire a Quickshell bar button when Illogical Impulse is detected
Ensure ~/.local/bin is on your shell PATH (Hyprland binds use the absolute path either way).
hyprgrok-uninstall
# or
./uninstall.sh --purge # also remove config/state| Bind | Action |
|---|---|
Super + Space |
Toggle glass panel |
Super + Shift + G |
Full interactive Grok session |
Super + Alt + G |
Print desktop context |
Super + Ctrl + G |
Analyze focused window |
Note: Illogical Impulse already uses
Super + Gfor its widget overlay, so HyprGrok defaults toSuper + Space.
hyprgrok # same as toggle
hyprgrok toggle # open / close panel
hyprgrok doctor # dependency check
hyprgrok ask "…" -c # headless prompt (+ context)
hyprgrok session # full TUI in project folder
hyprgrok ask-window # analyze focused window
hyprgrok context --json # dump desktop context
hyprgrok sessions # list Grok Build sessions (~/.grok)
hyprgrok sessions --resume <id>
hyprgrok history # prompt history from Grok Build
hyprgrok status # human status
hyprgrok status --waybar # JSON for status bars
hyprgrok hypr snapshot # compact Hyprland snapshot~/.config/hyprgrok/config.toml
grok_binary = "grok"
notify_on_complete = true
[panel]
position = "right"
width = 560
height = 980
port = 8765
auto_inject_context = false
browser = "auto"
[launch]
terminal = "auto"
preferred_terminals = ["kitty", "foot", "alacritty", "wezterm", "ghostty"]
headless_timeout_sec = 300Theme colors live under [theme].
No xAI keys are ever written here — sign in with grok login if needed.
Window size/position is controlled by Hyprland rules (see configs/hyprland/), so the panel stays fully on-screen.
After install you should get a robot chip on the bar:
| Click | Action |
|---|---|
| Left | Toggle panel |
| Right | Full Grok session |
| Middle | Analyze focused window |
Details: docs/QUICKSHELL.md
hyprgrok status --waybarSnippet: configs/waybar/hyprgrok.jsonc · docs/WAYBAR.md
┌─────────────────────────────────────────────┐
│ HyprGrok │
│ Glass Panel (HTML) ←→ Panel server │
│ │ (localhost only) │
│ │ ┌──────┴──────┐ │
│ │ │ Context │ │
│ │ │ (hyprctl) │ │
│ │ └──────┬──────┘ │
│ │ Sessions / history from │
│ │ ~/.grok/sessions │
└─────────┼────────────────┬──────────────────┘
│ │
└───────► Official `grok` CLI
(auth, models, tools)
- Quick answers:
grok -p "…" - Full sessions: interactive TUI in a terminal
- Resume:
grok --resume <session-id> - Panel HTTP API binds
127.0.0.1only
| Problem | Fix |
|---|---|
| Keybind does nothing | Run hyprctl reload. Confirm binds in ~/.config/hypr/custom/keybinds.lua (or conf sources). Default is Super+Space, not Super+G. |
| Panel doesn’t open | hyprgrok doctor · hyprgrok toggle · check ~/.config/hyprgrok/panel.log |
| “Focused on” shows HyprGrok | Update to latest — panel windows are skipped via focus history |
| Panel off-screen | Update rules (fixed 560px width + monitor_w-576 move). Close and reopen the panel. |
| No bar icon | Illogical Impulse: Settings → Bar → HyprGrok, then killall qs; qs -c ii & |
| Grok missing | Install official Grok Build so grok is on PATH (hyprgrok doctor) |
git clone https://github.com/dcbert/hyprgrok.git
cd hyprgrok
export PYTHONPATH=.
python3 -m hyprgrok doctor
python3 -m unittest discover -s tests -v
./install.shDocs:
| Doc | Topic |
|---|---|
| docs/TECH_SPEC.md | Architecture & API |
| docs/QUICKSHELL.md | II / Quickshell bar |
| docs/WAYBAR.md | Waybar module |
| docs/ACP.md | Future ACP notes |
| CHANGELOG.md | Release history |
| CONTRIBUTING.md | How to contribute |
- No xAI API keys handled or stored by HyprGrok
- Panel server listens on localhost only
- Reads Grok session metadata under
~/.grok/sessions(read-only) - Screenshots stay local (
~/.cache/hyprgrok/) unless you attach them in a Grok session yourself
See SECURITY.md.
MIT © HyprGrok contributors.
Not affiliated with xAI.
Grok Build is the official CLI; HyprGrok is an independent open-source companion for Hyprland.



