Release grok-build-hud v0.3.0: Claude-HUD-style same-window status for Grok Build
Multi-line tmux strip (context, quota, tools, todos, git), theme sync with Grok UI, full/essential/minimal presets, one-shot installer, EN+ZH docs, and 40 unit tests.
This commit is contained in:
@@ -0,0 +1,254 @@
|
||||
# grok-build-hud
|
||||
|
||||
**Claude-HUD-style live status for [Grok Build](https://x.ai/cli).**
|
||||
|
||||
> 中文安装与使用说明：[README.zh-CN.md](./README.zh-CN.md)
|
||||
|
||||
Always-on strip in the **same Terminal window** (tmux status — not a second window):
|
||||
|
||||
```text
|
||||
[Grok 4.5] │ my-project git:(main*) │ ● LIVE
|
||||
CTX ██████████░░░░ 70% (351k/500k) │ USE ███░░░░░░░░░░░ 23% weekly · 4d │ TIME 1h │ T 16 │ TOOLS 299
|
||||
◐ read_file… | ✓ grep ×3 | ▸ Ship HUD (2/5)
|
||||
```
|
||||
|
||||
Built for Claude Code users who already know **context bar + usage bar + tools/todos** — same glances on Grok.
|
||||
|
||||
> Grok has no native statusline API. This is the supported equivalent: a multi-line status strip + optional scrollback annotations.
|
||||
|
||||
---
|
||||
|
||||
## Requirements
|
||||
|
||||
- **Node.js 18+**
|
||||
- **tmux** (`brew install tmux` on macOS)
|
||||
- **Grok Build** CLI signed in (`grok login`)
|
||||
- Any terminal that can host tmux (tested on Apple Terminal / iTerm)
|
||||
|
||||
---
|
||||
|
||||
## Install
|
||||
|
||||
### A. One-shot script (recommended)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/sooneocean/grok-build-hud.git
|
||||
cd grok-build-hud
|
||||
bash scripts/install.sh
|
||||
```
|
||||
|
||||
This runs `npm install` → `build` → `npm link` → dashboard + hooks → `--theme auto` → `--preset full`.
|
||||
|
||||
### B. Manual steps
|
||||
|
||||
```bash
|
||||
git clone https://github.com/sooneocean/grok-build-hud.git
|
||||
cd grok-build-hud
|
||||
npm install
|
||||
npm run build
|
||||
npm link # puts grok-build-hud / grok-hud / grok-hud-run on PATH
|
||||
npm run install-local
|
||||
```
|
||||
|
||||
### C. From an already-cloned path
|
||||
|
||||
```bash
|
||||
cd /path/to/grok-build-hud
|
||||
bash scripts/install.sh
|
||||
```
|
||||
|
||||
### D. As a Grok plugin (optional)
|
||||
|
||||
```bash
|
||||
cd /path/to/grok-build-hud
|
||||
npm install && npm run build
|
||||
grok plugin install . --trust
|
||||
grok plugin enable grok-build-hud
|
||||
```
|
||||
|
||||
In Grok: `/hooks` → press `r` to reload.
|
||||
|
||||
### PATH fix (`command not found`)
|
||||
|
||||
```bash
|
||||
# add to ~/.zshrc or ~/.bashrc
|
||||
export PATH="$(npm prefix -g)/bin:$HOME/.local/bin:$PATH"
|
||||
```
|
||||
|
||||
Then `source ~/.zshrc` and verify: `which grok-hud-run`.
|
||||
|
||||
---
|
||||
|
||||
## Daily use (same window — no second pane)
|
||||
|
||||
```bash
|
||||
# Start Grok with the multi-line HUD at the bottom of THIS tab
|
||||
grok-hud-run
|
||||
```
|
||||
|
||||
| Row | Content (Claude HUD analogue) |
|
||||
|-----|--------------------------------|
|
||||
| 1 | Model · project · git · live · title · effort |
|
||||
| 2 | **Context** bar + tokens · **Usage/quota** · time · turns · tools · errors · diff |
|
||||
| 3 | Tool activity · agents · todos · GrokBuild product share |
|
||||
|
||||
The strip refreshes about once per second while the session is open.
|
||||
|
||||
### Useful commands
|
||||
|
||||
```bash
|
||||
grok-build-hud --once --follow-active # print full HUD once
|
||||
grok-hud status # same
|
||||
grok-hud stop # stop background updater
|
||||
grok-build-hud --preset full|essential|minimal
|
||||
grok-build-hud --theme auto # follow Grok [ui].theme
|
||||
grok-build-hud --theme tokyonight # lock palette
|
||||
```
|
||||
|
||||
### Refresh tmux after config change
|
||||
|
||||
```bash
|
||||
tmux source-file ~/.grok/hud/tmux.conf && tmux refresh-client -S
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Display preset & toggles
|
||||
|
||||
`~/.grok/hud/config.json`
|
||||
|
||||
| Preset | Rows | Contents |
|
||||
|--------|------|----------|
|
||||
| **full** (default) | 3 | Everything (Claude “Full”) |
|
||||
| **essential** | 2 | Model/git + context/usage + activity |
|
||||
| **minimal** | 1 | Dense single row |
|
||||
|
||||
Key options:
|
||||
|
||||
```json
|
||||
{
|
||||
"preset": "full",
|
||||
"statusLines": 3,
|
||||
"bold": true,
|
||||
"barWidth": 14,
|
||||
"pathLevels": 2,
|
||||
"display": {
|
||||
"showContextBar": true,
|
||||
"contextValue": "both",
|
||||
"showUsage": true,
|
||||
"showToolActivity": true,
|
||||
"showTodos": true,
|
||||
"showAgents": true,
|
||||
"showDiffStats": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Theme (matches Grok UI)
|
||||
|
||||
Reads `~/.grok/config.toml`:
|
||||
|
||||
```toml
|
||||
[ui]
|
||||
theme = "tokyonight" # also: groknight, grokday, rosepinemoon, oscuramindnight, auto
|
||||
```
|
||||
|
||||
```bash
|
||||
grok-build-hud --theme auto # follow Grok config (default)
|
||||
```
|
||||
|
||||
### Readability
|
||||
|
||||
- `bold: true` — bold values (default)
|
||||
- `barWidth: 14` — thicker progress bars
|
||||
|
||||
True **font size** is Terminal’s font (tmux cannot set a separate size for the status strip).
|
||||
|
||||
---
|
||||
|
||||
## How it works
|
||||
|
||||
```text
|
||||
Grok sessions ──► ~/.grok/sessions/**/signals.json
|
||||
──► updates.jsonl (tools / agents / todos)
|
||||
──► summary.json (title, effort, model)
|
||||
auth.json ──► cli-chat-proxy billing (weekly quota + monthly)
|
||||
│
|
||||
▼
|
||||
dashboard daemon (~500ms)
|
||||
│
|
||||
┌───────────┼───────────┐
|
||||
▼ ▼ ▼
|
||||
tmux-lines.txt status.txt hooks annotations
|
||||
│
|
||||
▼
|
||||
same-window tmux status (1–3 rows)
|
||||
```
|
||||
|
||||
No second window. No cloud upload of your code by this tool (read-only local session files + your existing Grok auth for billing).
|
||||
|
||||
---
|
||||
|
||||
## Migrating from Claude HUD
|
||||
|
||||
See **[MIGRATION-FROM-CLAUDE.md](./MIGRATION-FROM-CLAUDE.md)** for option-by-option mapping.
|
||||
|
||||
| Claude HUD | Grok Build HUD |
|
||||
|------------|----------------|
|
||||
| Statusline under prompt | Same-window tmux multi-line strip |
|
||||
| Full / Essential / Minimal | `--preset full\|essential\|minimal` |
|
||||
| Context + Usage bars | Same layout on line 2 |
|
||||
| Tools / agents / todos | Line 3 |
|
||||
| `/claude-hud:setup` | `--install-dashboard` + `grok-hud-run` |
|
||||
|
||||
---
|
||||
|
||||
## Uninstall
|
||||
|
||||
```bash
|
||||
grok-build-hud --uninstall-dashboard
|
||||
grok-build-hud --uninstall-hooks
|
||||
npm unlink -g grok-build-hud # if you used npm link
|
||||
```
|
||||
|
||||
Optional cleanup: `~/.grok/hud/`, `~/.grok/hooks/grok-build-hud.json`.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | Fix |
|
||||
|---------|-----|
|
||||
| `command not found` | Fix PATH (above) or run `node bin/grok-hud-run.js` |
|
||||
| No bottom strip | Use `grok-hud-run`; install tmux; re-run `--install-dashboard` |
|
||||
| Usage shows `—` | `grok login`, then `grok-hud status` |
|
||||
| Colors clash with TUI | `grok-build-hud --theme auto` |
|
||||
| Stale numbers | `grok-hud stop` then `grok-hud-run` |
|
||||
| Text too small | Increase Terminal font; keep `bold` / `barWidth` |
|
||||
|
||||
---
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm test # build + 40 unit tests
|
||||
npm run build
|
||||
grok plugin validate . # if Grok CLI is available
|
||||
```
|
||||
|
||||
See [CHANGELOG.md](./CHANGELOG.md) and [CONTRIBUTING.md](./CONTRIBUTING.md).
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
|
||||
---
|
||||
|
||||
## Disclaimer
|
||||
|
||||
Third-party tool. Billing/quota display depends on xAI session auth and API shapes that may change. Not affiliated with xAI.
|
||||
Reference in New Issue
Block a user