Redredchen01
bb6a1321fb
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.
255 lines
6.3 KiB
Markdown
255 lines
6.3 KiB
Markdown
# 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.
|