# codex-hud

**Repository Path**: maoning325/codex-hud

## Basic Information

- **Project Name**: codex-hud
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-19
- **Last Updated**: 2026-05-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# codex-hud

`codex-hud` 是一个面向 Codex CLI 的终端 HUD 工具，用来展示当前上下文使用情况、5 小时额度状态和周额度状态。

它的目标不是替换 Codex 本体，而是在尽量不侵入 Codex CLI 的前提下，把你最关心的额度和上下文信息持续展示出来。

当前版本重点解决三件事：

- 展示当前上下文使用情况
- 展示 5 小时额度状态
- 展示周额度状态

## 当前状态

这是一个可用的第一版，已经提供以下模式：

- 单次快照输出
- 持续 watch 模式
- 包装 Codex 交互会话的 `run` 模式
- 环境自检 `doctor` 模式

当前推荐的日常使用方式是：

```bash
codex-hud run -- --search
```

这会在启动真实 Codex 会话的同时显示 HUD。默认显示位置是终端标题栏。

## 安装

本地安装并用于日常命令：

```bash
npm install
npm run build
npm link
```

安装后可直接使用：

```bash
codex-hud
```

### Windows PowerShell

Windows 原生环境推荐使用标题栏显示模式：

```powershell
npm install
npm run build
npm link
$env:CODEX_HUD_RUN_DISPLAY="title"
codex-hud run -- --search
```

`codex-hud run` 在 Windows 下会直接启动 `codex`，同时后台 watcher 会持续刷新终端标题栏。推荐使用 Windows Terminal 或支持 OSC title 序列的现代终端。

## 使用方式

输出一次当前 HUD 快照：

```bash
codex-hud
```

持续输出 HUD 更新：

```bash
codex-hud --watch
```

包装一个内联 Codex 会话，并在同一终端中显示 HUD：

```bash
codex-hud run -- --search
```

只做环境检查，不启动会话：

```bash
codex-hud doctor
```

查看帮助：

```bash
codex-hud --help
```

## HUD 示例

在不同终端和数据可用性下，HUD 文案会略有变化，典型格式类似：

```bash
[Codex]  codex-hud ~ | Ctx 41% 106k | 5h 22% (3h 53m) | 7d 16% (2d 9h)
```

其中：

- `Ctx` 表示当前上下文使用占比和已用 token 数
- `5h` 表示 5 小时窗口剩余额度
- `7d` 表示 7 天额度剩余额度

## 运行模式

### 默认模式

默认模式输出一次 HUD，然后退出。适合快速查看当前状态。

### `--watch`

`--watch` 会持续运行，保持 app-server 连接，并在需要时从 SQLite 回退刷新上下文数据。

### `run`

`run` 模式会：

1. 启动 HUD watcher
2. 启动真实的 `codex --no-alt-screen ...`
3. 在 TTY 环境中默认将 HUD 写入终端标题栏
4. 在非 TTY 环境中回退为普通文本 HUD 输出

示例：

```bash
codex-hud run -- --model gpt-5.4
```

如果你希望继续使用顶部栏，可以设置：

```bash
CODEX_HUD_RUN_DISPLAY=topbar codex-hud run -- --model gpt-5.4
```

同时启用标题栏和顶部栏：

```bash
CODEX_HUD_RUN_DISPLAY=both codex-hud run -- --model gpt-5.4
```

### `doctor`

`doctor` 模式会检查：

- `codex` 二进制是否可执行
- `~/.codex/state_5.sqlite` 是否存在
- `codex app-server` 是否能够成功初始化

## 数据来源

- 主路径：Codex app-server
- 回退路径：`~/.codex/state_5.sqlite`

当前实现里：

- 额度信息主要来自 app-server 的 live 数据
- 上下文信息在实际使用中仍较多依赖 SQLite 回退

这意味着：

- 5h / 周额度的刷新通常更可靠
- `Ctx` 会自动更新，但实时性通常不如额度数据稳定

## 环境变量

- `CODEX_HUD_FALLBACK_POLL_MS`
  - 覆盖 SQLite 回退刷新间隔，单位毫秒
- `CODEX_HUD_INLINE_READY_TIMEOUT_MS`
  - 覆盖 `run` 模式等待首条内联 HUD 的超时时间，单位毫秒
- `CODEX_HUD_RUN_DISPLAY`
  - 控制 `run` 模式 HUD 显示位置
  - 可选值：`title`、`topbar`、`both`
  - 默认值：`title`

## HUD 语义

HUD 默认只显示 3 块：

- `Ctx <percent> <usedTokens>`
- `5h <remainingPercent> (<resetIn>)`
- `7d <remainingPercent> (<resetIn>)`

token 数会自动做单位换算，例如：

- `950`
- `106k`
- `1.3m`

## 已知限制

- Codex app-server 目前仍是 experimental
- 冷启动阶段可能会短暂显示 stale 数据
- 上下文 live 更新链路在实际运行中仍不如额度链路稳定
- `run` 模式默认使用终端标题栏；如果终端不显示标题栏，建议改用 `CODEX_HUD_RUN_DISPLAY=topbar`
- 即使使用顶部栏，也还不是真正嵌入 Codex TUI 内部状态栏

## 故障排查

如果 `npm link` 之后找不到 `codex-hud` 命令，优先检查：

```bash
which codex-hud
echo $PATH
```

常见原因不是 link 失败，而是当前 shell 会话还没刷新命令缓存，或者 `PATH` 里没有全局 npm bin 目录。可以尝试：

```bash
exec zsh
rehash
hash -r
```

Windows 下的 SQLite 回退路径仍依赖外部 `sqlite3` 命令。如果回退数据无法读取，请安装 SQLite CLI 并确保 `sqlite3` 已加入 `PATH`。主路径仍优先使用 Codex app-server。

## 发布前检查

如果准备发布或打包，建议先执行：

```bash
npm run typecheck
npm test
npm run build
npm pack --dry-run --cache /tmp/codex-hud-npm-cache
```

## License

MIT