codex-vitals

README

🫀 codex-vitals

A lightweight Go HUD for OpenAI Codex CLI sessions See model, reasoning effort, git status, working directory, context usage, and 5-hour / weekly usage limits at a glance.

English · 한국어

Quick install · Preview · What it shows · Options · FAQ

---

✨ Highlights

• 🤖 Current model / effort — shows the latest turn info from your Codex session, e.g. gpt-5.5 ⚡xhigh.
• 🧠 Accurate context % — reads token usage from the Codex rollout and computes context-window usage that matches Codex's own status line (see Context %).
• 📊 5H / 7D usage bars — 5-hour and weekly rate-limit usage with reset times.
• 🌿 Git status — current branch, dirty count, and clean state.
• 🎨 Terminal colors — ANSI truecolor with gradient block bars.
• 🪶 Small single binary — written in Go, runs without a Node runtime.

---

🚀 Quick install

One line (macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/WinningBean/codex-vitals/main/install.sh | bash

Downloads the prebuilt binary for your OS/arch into ~/.local/bin (falls back to building from source if no release is published yet).

go install

Easiest if you have Go 1.22+:

go install github.com/WinningBean/codex-vitals/cmd/codex-vitals@latest

Make sure $GOPATH/bin (or $HOME/go/bin) is on your PATH, then:

codex-vitals -once -context-mode current-hud -style answer-footer

Build from source

git clone https://github.com/WinningBean/codex-vitals.git
cd codex-vitals
CGO_ENABLED=0 go build -o codex-vitals ./cmd/codex-vitals
./codex-vitals -once -context-mode current-hud -style answer-footer

Run during local development

go run ./cmd/codex-vitals -once
go run ./cmd/codex-vitals -once -context-mode current-hud -style answer-footer

---

📸 Preview

Colors show in a real terminal; GitHub may not render ANSI colors in the text block below.

answer-footer style

  🤖 gpt-5.5 ⚡xhigh ✅ clean no env
  📂 ~/Documents/Github/codex-vitals 🌿(main) 🧾 2.1M tokens ⏰ 42m
  🧠 Context  ██████████░░░░░░░░░░ 49% used (126k/258k)
  🚀 Usage 5H █████████████░░░░░░░ 67% (Reset 2h33m left)
  ⭐ Usage 7D ████████░░░░░░░░░░░░ 42% (Reset Fri 16:45)

codex-vitals -once -context-mode current-hud -style answer-footer

single-line style

gpt-5.5 xhigh · ~/Documents/Github/codex-vitals · Context 49% used · 5h 33% left · weekly 58% left

codex-vitals -once -context-mode current-hud -style current-hud

compact style

🤖 gpt-5.5 xhigh · 🌿 main · ~/Documents/Github/codex-vitals · Ctx ███░░░ 49% (126k/258k) · 5h 33% · wk 58%

codex-vitals -once

---

🎨 What it shows

Item	Meaning
🤖 Model	Latest model of the current Codex session
⚡ Effort	Reasoning effort (low, medium, high, xhigh, …)
📝 Git dirty	Number of tracked changed files, or clean state
🐍 Env	Active CONDA_DEFAULT_ENV or VIRTUAL_ENV
📂 Path	Working directory of the current session
🌿 Branch	Current git branch
🧾 Tokens	Cumulative session token usage
⏰ Time	Elapsed time since the session started
🧠 Context	Context-window usage percentage and token count
🚀 Usage 5H	5-hour usage limit and time to reset
⭐ Usage 7D	Weekly usage limit and reset time

---

🧠 Context % calculation

codex-vitals offers two modes so it can match both stock Codex and a patched Codex HUD.

Mode	Formula	Matches
codex (default)	(total_tokens − 12000) / (model_context_window − 12000)	stock Codex status line
current-hud	(input_tokens + cached_input_tokens) / model_context_window	a patched Codex HUD

Stock Codex reserves a 12000-token baseline (system prompt, tools, and room to run /compact), so the default codex mode subtracts 12000 from both total_tokens and model_context_window. For small models whose window is ≤ 12000, it falls back to the raw bounded ratio so usage is never reported as a misleading 0% or 100%.

If the number doesn't match your running HUD, you're probably on a patched Codex build — use current-hud:

codex-vitals -once -context-mode current-hud -style answer-footer

---

⚙️ Options

-codex-home string
    Path to CODEX_HOME. Defaults to $CODEX_HOME or ~/.codex

-rollout string
    Use a specific rollout JSONL file directly

-context-mode string
    Context usage formula: codex or current-hud

-style string
    Output style: compact, current-hud, answer-footer

-interval duration
    Refresh interval. Default 1s

-once
    Render once and exit

-no-color
    Output without ANSI colors

---

🧪 Try it with a specific session

codex-vitals \
  -once \
  -rollout /path/to/session.jsonl \
  -context-mode current-hud \
  -style answer-footer

If colors look broken in your environment, add --no-color.

---

📁 Data read

By default it reads:

• ~/.codex/sessions/**/*.jsonl
• $CODEX_HOME/config.toml / ~/.codex/config.toml
• session_meta, turn_context, token_count from the rollout
• primary / secondary rate limits

It finds the most recent Codex session and renders it; use -rollout to pin a specific file.

---

🧩 Using it in tmux / as a footer

From inside a tmux session (e.g. where Codex is running), add a HUD pane at the bottom:

scripts/tmux-hud.sh                 # answer-footer, refreshing every 1s
scripts/tmux-hud.sh -style current-hud
CODEX_VITALS_TMUX_HEIGHT=7 scripts/tmux-hud.sh

Focus returns to your original pane; Ctrl+C in the HUD pane closes it. Or run it directly:

# render once
codex-vitals -once -context-mode current-hud -style answer-footer

# refresh every second
codex-vitals -context-mode current-hud -style answer-footer -interval 1s

# no color, for logs / README
codex-vitals -once -context-mode current-hud -style answer-footer --no-color

---

✅ Requirements

Item	Why
Go 1.22+	Build and go install
A Codex CLI session	~/.codex/sessions rollout data
git	Branch / dirty status
truecolor terminal	Gradient bar colors

With --no-color, text output works fine even without truecolor.

---

🧹 Uninstall

If installed via go install, just remove the binary:

rm "$(go env GOPATH)/bin/codex-vitals"

Built from source? Remove the binary you created:

rm ./codex-vitals

codex-vitals installs no daemon, launch agent, or shell-rc changes.

---

🙋 FAQ

Colors don't show in the README or chat. Markdown / chat renderers usually don't interpret ANSI escapes as colors. Run it in a real terminal without --no-color to see them.

The number differs slightly from my running HUD. Rollouts update live, so token counts can shift by ~1k depending on when you run. To match your HUD's formula, use -context-mode current-hud.

5H shows used, not left. The answer-footer style shows usage limits as used-percent to match a running HUD. The current-hud single line shows remaining (left) instead.

Do I need Node? No. codex-vitals itself is a Go binary.

Do I need a Nerd Font? No. It uses standard emoji and Unicode block characters.

---

Acknowledgements

• The persistent terminal-HUD idea comes from jarrodwatts/claude-hud (for Claude Code).
• The layout and gradient bar were inspired by AwesomeJun/CC-statusline.
• Reads session data written by openai/codex.

---

Built for Codex users who want to see the real session vitals at a glance. 🫀