Files

T

Redredchen01 e32e0df209 Make Chinese README primary; ship English as README.en.md

Restructure docs so README.md is full Chinese documentation with TOC.
English content moves to README.en.md; drop README.zh-CN.md. Align
CONTRIBUTING, install script, package/plugin descriptions, and skill links.

2026-07-17 16:32:20 +08:00

6.3 KiB

Raw Blame History

grok-hud

Grok Build 实时多行状态条

English: README.en.md

在同一个 Terminal 标签页底部常驻显示（tmux 状态栏，不另开窗口）：

Grok 4.5 · AI FILM SPACE/0717 · ●
窗 ██████░░░░ 50% (252k/500k) · 入 2,189,879  出 9,468  缓 2,172,032 99% · 额 24% · 轮7 · 具212
◐ read_file… · ✓ grep ×3 · ▸ 待办

能力	说明
上下文	窗口占用 % 与 token 数
配额	周/月用量（需已 `grok login`）
Token 明细	入 / 出 / 缓存 / 推理（来自会话 `turn_completed`）
活动	工具、agent、todos
主题	跟随 Grok `[ui].theme`，不锁死
多终端	每个标签页独立 session，互不串线
语言	默认简体中文，可切英文 / 繁體

仓库：http://172.238.15.154:3000/Redredchen01/grok-hud

依赖

依赖	说明
Node.js 18+	`node -v`
tmux	macOS：`brew install tmux`
Grok Build	已登录：`grok login`
终端	Terminal / iTerm 等（在 tmux 内运行即可）

安装

方式 A：从 Gitea 克隆（推荐）

git clone http://172.238.15.154:3000/Redredchen01/grok-hud.git
cd grok-hud
bash scripts/install.sh

会自动：npm install → 编译 → npm link → 装 dashboard / hooks → 主题跟随 → 预设 full → 语言中文。

方式 B：已有源码目录

cd /path/to/grok-hud
bash scripts/install.sh
# 或：
npm install && npm run build && npm link
npm run install-local

方式 C：作为 Grok 插件（可选）

cd /path/to/grok-hud
npm install && npm run build
grok plugin install . --trust
grok plugin enable grok-build-hud

在 Grok 内执行 /hooks 后按 r 重载 hooks。

命令找不到时

写入 ~/.zshrc：

export PATH="$(npm prefix -g)/bin:$HOME/.local/bin:$PATH"

然后：

source ~/.zshrc
which grok-hud

日常使用

# 1. 打开 Terminal（会自动确保 HUD 后台更新器）
# 2. 输入：
grok

底部即出现状态条。

# 不要 HUD 的裸命令（脚本 / 打印模式）
GROK_NO_HUD=1 grok -p "hello"

# 兼容旧入口
grok-hud-run

生命周期：开 Terminal 即就绪；不是电脑开机自启。
并行开发：每个标签页独立 Grok session，各自 grok 即可。

设定（语言 / 预设）

# 交互设定（默认界面为中文）
grok-hud settings

# 快捷切语言
grok-hud lang zh    # 简体中文（默认）
grok-hud lang en    # English
grok-hud lang tw    # 繁體中文

命令	作用
`grok-hud status`	打印当前完整状态一次
`grok-hud stop`	停后台刷新
`grok-build-hud --preset full`	三行全开（默认）
`grok-build-hud --preset essential`	两行
`grok-build-hud --preset minimal`	一行
`grok-build-hud --theme auto`	跟随 Grok 主题（推荐）

改完配置后若条未变，在 tmux 内：

tmux source-file ~/.grok/hud/tmux.conf && tmux refresh-client -S

状态条说明

行	内容
第 1 行	模型 · 项目 · git · 在线 · 标题 · effort
第 2 行	窗进度条 + token · 额配额 · 入/出/缓 · 轮次 · 工具 · 错误
第 3 行	最近工具 · agents · todos · GrokBuild 占比

中文标签：窗 / 额 / 入 / 出 / 缓 / 思 / 轮 / 具
英文标签：ctx / use / i / o / c / r / t / ⚙

宽度会随窗口自适应：窄窗自动减行、丢次要字段，避免挤出屏外。

会话开启时约每秒刷新。

配置

文件：~/.grok/hud/config.json

预设	行数	内容
full（默认）	3	全部信息
essential	2	模型/git + 上下文/配额 + 活动
minimal	1	单行压缩

常用字段：

language：zh-Hans（默认）/ en / zh-Hant
bold: true — 粗体数值
barWidth: 14 — 进度条宽度
字号由 Terminal 字体决定，状态栏无法单独放大。

主题

HUD 跟随 Grok，不锁死某一套色：

Grok：/theme 或 ~/.grok/config.toml → [ui] theme = "…"
theme = "auto" 时：系统深色 → auto_dark_theme，浅色 → auto_light_theme
约 1 秒内重绘状态条

可选临时锁色（一般不必）：

GROK_HUD_LOCK=1 grok-build-hud --theme tokyonight
# 恢复跟随：
grok-build-hud --theme auto

浅色（如 grokday）使用纸色底 + 深字，避免白底看不清。

工作原理

读本机 ~/.grok/sessions/**（signals / updates / summary）
用已有 Grok 登录查配额
后台 daemon 写入 ~/.grok/hud/ 与按 tmux 会话隔离的状态文件
同窗口 tmux 状态栏 展示

不上传你的代码。

卸载

grok-build-hud --uninstall-dashboard
grok-build-hud --uninstall-hooks
npm unlink -g grok-build-hud   # 若用过 npm link

可选删除：~/.grok/hud/、~/.grok/hooks/grok-build-hud.json。

常见问题

现象	处理
`command not found`	检查 PATH；或 `node bin/grok-hud.js status`
底部没有状态条	用 `grok` 启动；已装 tmux；执行 `--install-dashboard`
配额显示 `—`	先 `grok login`，再 `grok-hud status`
颜色不对	`grok-build-hud --theme auto`，与 Grok 主题一致
状态不更新	`grok-hud stop` 后重新 `grok`
多终端串会话	更新到新版；每标签独立 `grok`，勿共用旧 `grok-hud` tmux 名
字太小	放大 Terminal 字体；保持 `bold` / `barWidth`

开发

npm install
npm test          # 编译 + 单元测试
npm run build

Commit message 用英文
用户文档以中文 README 为主，英文见 README.en.md
贡献说明：CONTRIBUTING.md

License

MIT。第三方工具，与 xAI 无官方从属关系；配额接口以 xAI 实际 API 为准，可能变更。

6.3 KiB Raw Blame History Unescape Escape