codex-usage-hud v1.0.5

codex-usage-hud v1.0.5 - Renderer Session Follow Hotfix

✨ Windows installer now available. One-click install, no Python environment needed.

TL;DR

v1.0.5 is a Windows-first hotfix for Codex App sluggishness while clicking or
switching conversations. Renderer mode now receives active-session changes
through a CDP binding from the Codex renderer instead of using the Windows
native title/UIA watcher as the default hot path.

Fixed

• Replaced renderer-mode active-session follow with a CDP binding emitted from
  the in-renderer HUD script, with the existing HTTP bridge left as fallback.
• Suspended the native active-title watcher in renderer mode so Windows UIA is
  no longer polled during normal Codex sidebar/session switching.
• Debounced renderer filesystem change wakeups and throttled active work rescans
  to reduce CPU bursts when session files or settings change.
• Resolved renderer thread ids from state_5.sqlite before recursive session
  scans, which avoids unnecessary disk traversal during conversation switches.
• Tightened sidebar click detection so nested buttons still report the parent
  conversation row and strip trailing relative-time text from the session title.

Verification

python -m pytest
python -m pytest -m ui
python -m compileall -q src tools tests
python tools/pre_release_check.py
python tools/build_installer.py

Notes

• Windows installer asset:
  codex-usage-hud-v1.0.5-windows-x64-setup.exe.
• Qt/Tk main HUD modes remain deprecated; this fix keeps the product path on
  renderer/CDP.

codex-usage-hud v1.0.2 · Completed Bubble Transition Patch

codex-usage-hud v1.0.2 · Completed Bubble Transition Patch

Release body for GitHub Releases.

TL;DR

v1.0.2 is a patch release that keeps the v1.0.0 Windows installer line and
fixes the completed-bubble workflow so overlay cards animate on the intended
right-edge path, preserve the richer completed badge details, avoid showing
historical completions at startup, and keep renderer session switching stable
on more local CDP endpoint variants.

Fixed

• Completed work-overlay cards now shrink in place, rise on the right-side
  vertical track, and return through the same path when a finished task becomes
  active again.
• The settled completed badge again shows the title, runtime, token/cost/cache
  metrics, workdir label, and the existing click targets for close / jump-back.
• Startup filtering no longer surfaces historical completed tasks as fresh
  green completion bubbles before the current runtime has seen them run.
• Work-overlay click commands now drain on a background pump so session
  activation stays responsive while the renderer / Tk HUD keeps repainting.
• The CDP websocket handshake now formats IPv6 and loopback authority/origin
  headers safely for local debugger endpoints.

Verification

python -m unittest discover -s tests
python -m compileall -q src tools tests
python tools/pre_release_check.py
python tools/build_installer.py

Notes

• Windows installer asset naming is now
  codex-usage-hud-v1.0.2-windows-x64-setup.exe.
• Runtime behavior remains local-first: no telemetry, no log upload, and no
  prompt/response upload.

codex-usage-hud v1.0.1 · Archived Sessions Summary Patch

codex-usage-hud v1.0.1 · Archived Sessions Summary Patch

Release body for GitHub Releases.

TL;DR

v1.0.1 is a patch release that keeps the v1.0.0 Windows installer line and
fixes session discovery so the HUD scans the sibling archived_sessions tree,
keeps polling after event gaps, and removes a redundant Tk header close button.

Fixed

• UsageSummaryCache now treats archived_sessions as a sibling scan root
  when sessions is the active session tree.
• Active-session detection now considers archived session trees too, and the
  resolver can still fall back cleanly when tracker state is unmatched.
• The realtime watcher keeps issuing backstop polls after event gaps so title
  changes still land when event signals go quiet.
• The Tk expanded header no longer shows a redundant close button.
• Added regression coverage so day/week totals stay correct when archived logs
  sit outside the live folder, and the active-session / Tk layout changes stay
  covered.

Verification

python -m unittest discover -s tests
python -m compileall -q src tools tests
python tools/pre_release_check.py

Notes

• Windows installer asset naming remains
  codex-usage-hud-v1.0.1-windows-x64-setup.exe.
• Runtime behavior remains local-first: no telemetry, no log upload, and no
  prompt/response upload.

v1.0.0 · Windows Installer Edition

codex-usage-hud v1.0.0 · Windows Installer Edition

Release body for GitHub Releases.

TL;DR

v1.0.0 is the first supported Windows installer release for
codex-usage-hud. It keeps the local-first renderer/Tk HUD behavior from the
v0.x preview line, adds version display and GitHub Release update checks, and
ships a Windows setup package named:

codex-usage-hud-v1.0.0-windows-x64-setup.exe

Headliners

Windows installer

• Adds an Inno Setup 6 installer that installs to
  %LOCALAPPDATA%\Programs\codex-usage-hud.
• Creates Start Menu shortcuts for starting the daemon, stopping the HUD, and
  checking updates.
• Offers an optional desktop shortcut and optional startup registration.
• Stops an existing HUD before replacing the executable during install/update.

Version display and auto update

• Adds codex-hud --version, codex-hud --check-update, and
  codex-hud --update.
• Adds a renderer HUD "版本更新" tab and a Tk fallback "版本更新" tab.
• Checks GitHub Releases, selects the Windows setup asset, downloads it, and
  launches the installer.

Homepage refresh

• Makes Chinese the default GitHub README and adds README_EN.md.
• Keeps an empty sponsors table with the sponsor contact link:
  512145547@qq.com.
• Keeps the community/support section as "敬请期待" and uses bundled Alipay /
  WeChat support QR assets.
• Adds v1.0.0 HUD screenshots and a pain-points section focused on token/cost
  transparency, waiting-state visibility, and custom day/week budgets.

Deprecated historical tags

v0.1.0, v0.2.0, and v0.3.0 remain available as historical alpha / preview
tags. New users should install v1.0.0 or newer from GitHub Releases.

Verification

python -m unittest tests.test_updater tests.test_build_installer tests.test_build_exe tests.test_renderer_hud
python tools/build_installer.py

Notes

• Windows is the only supported installer target in this release.
• Runtime behavior remains local-first: no telemetry, no log upload, and no
  prompt/response upload.

v0.3.0 · Renderer Timeline Edition

codex-usage-hud v0.3.0 · Renderer Timeline Edition

Release body for GitHub Releases.

TL;DR

v0.3.0 moves the live HUD into the Codex renderer when a local Chrome
DevTools Protocol target is available, while keeping the Tk HUD as the fallback
surface. The renderer HUD follows the Codex conversation title bar and composer
footer inside the same rendering plane, reducing the jitter that came from
separate native overlay windows.

Headliners

Renderer-injected HUD

• Adds a CDP-driven renderer HUD with a top session/budget panel and a bottom
  request timeline panel.
• Keeps the HUD inside the Codex renderer surface instead of tracking a separate
  native overlay window.
• Preserves the application title-bar drag region while allowing the HUD panels
  themselves to move, resize, and expand.

Better Codex App following

• Resolves the active Codex conversation through CDP by session id and title
  before falling back to native title tracking.
• Anchors the top HUD around the real conversation title, three-dot menu, and
  right-side header buttons so long titles are not covered.
• Anchors the bottom HUD to the composer footer row so image and attachment
  previews do not push it upward.

Cleaner request timeline

• Reorders bottom request stats so input is followed by cache hit rate, then
  output/reasoning, cached tokens, and total tokens.
• Removes redundant reset buttons and decorative glyphs from the renderer HUD.
• Fixes the expanded request timeline header so "round flow / newest first" no
  longer overlaps the request rows.

Verification

python -m compileall -q src tests
python -m unittest discover -s tests

Current validation: 112 unit tests passing.

Notes

• The renderer HUD is preferred by default. Use --tk-hud or
  --no-renderer-hud to force the legacy Tk HUD.
• The implementation remains local-first and dependency-free at runtime; CDP is
  used only against the local Codex renderer debug target when available.

v0.2.0 · Smart Daemon Edition

🚀 codex-usage-hud v0.2.0 · Smart Daemon Edition

⚡ TL;DR / 一句话总结

v0.2.0 turns codex-usage-hud into a smart, invisible, persistence-ready
Windows daemon built on the Python standard library and ctypes only. It
watches Codex.exe with ultra-light polling, hides its own console noise, and
can persist through either the Startup folder or HKCU registry flow.

v0.2.0 将 codex-usage-hud 进化为一个 聪明、无声、可持久化的
Windows 守护进程：完全基于 Python 标准库 + ctypes，以超低开销轮询
监控 Codex.exe，自动隐藏控制台黑框，并可通过“启动文件夹”或 HKCU
注册表路径实现开机即用。

---

✨ Headliners / 核心亮点

1) Smart Daemon Mode

Pure stdlib + ctypes, ultra-low power polling, and process-anchored
lifecycle control.

• EN: The daemon is driven by the Python standard library and ctypes
  alone, with a 250ms~500ms low-power polling loop that keeps the footprint
  intentionally small.
• 中文： 守护模式完全由 Python 标准库和 ctypes 驱动，采用
  250ms~500ms 的低功耗轮询节奏，把常驻开销压到极低。
• EN: It appears automatically when Codex.exe starts and exits with the
  process, so the HUD stays attached to the real session lifecycle.
• 中文： 它会在 Codex.exe 启动时自动出现，并在进程关闭后自动退出，
  让 HUD 与真实会话生命周期保持同步。

Codex.exe starts  ──► daemon wakes up
poll every 250-500ms ─► low-cost monitoring
Codex.exe exits    ──► daemon exits with it

2) Zero Window Noise

No black console flash. No accidental focus steal. No visual clutter.

• EN: Startup uses Windows API-backed hidden-console behavior so the daemon
  can guard the session without leaving a console window behind.
• 中文： 启动阶段调用 Windows API 隐身控制台，让守护进程在后台安静
  运行，不留下烦人的黑框。
• EN: The result is a genuinely silent guardian: present when needed,
  invisible when not.
• 中文： 结果就是一个真正“无感守护”的后台代理：需要时存在，不需要时
  完全不打扰。

3) One-Click Persistence

Install once, choose your persistence path, and you are ready for reboot.

• EN: install.bat now supports optional startup persistence through either
  a hidden VBS launcher in the Windows Startup folder or a registry-based
  HKCU Run entry.
• 中文： install.bat 支持可选持久化：既可以走 Windows 启动文件夹的
  隐藏 VBS 流，也可以写入 HKCU Run 注册表项。
• EN: That makes the daemon practical for everyday use while still keeping
  the setup flow simple and explicit.
• 中文： 这样既保留了“一键可用”的体验，也让安装过程保持清晰、可控。

.\install.bat

---

🧪 Verification Snapshot / 验证快照

• 71 unit tests passing
• Standard-library-only implementation
• Windows-first smart daemon behavior validated

python -m unittest discover -s tests

---

🔧 What shipped / 本次交付了什么

• Smart daemon loop with lightweight ctypes-driven process watching

• Hidden-console startup behavior for zero window noise

• Optional persistence via Startup folder or HKCU registry

• Continued emphasis on local-only behavior and no extra dependencies

• Regression coverage expanded to keep the daemon and startup behavior honest

• 基于 ctypes 的智能守护循环

• 隐藏控制台启动，消除窗口噪声

• 启动文件夹 / HKCU 双路径可选持久化

• 继续坚持本地优先与零额外依赖

• 持续扩展回归测试，锁定守护和启动行为

---

v0.1.0 Alpha

🚀 codex-usage-hud v0.1.0 Alpha

English
codex-usage-hud is now public in its first alpha form: a local-first usage
HUD for Codex App that stays 100% offline, tracks tokens and cost in real time,
computes cached-token discounts precisely, and ships with zero external
dependencies.

中文
codex-usage-hud 现已进入首次公开 Alpha：它是一个面向 Codex App 的
local-first 用量 HUD，100% 离线运行，实时追踪 token 与成本，精确计算
cached token 折扣，并且保持 0 外部依赖。

✨ Highlights / 亮点

• 🔒 Local-first, 100% offline safe
  • All parsing, aggregation, and display stay on your machine.
  • 所有解析、聚合与展示都只在本地完成。
• 📊 Real-time Token & Cost Tracker
  • Live JSONL + SQLite SSE tracking keeps the HUD close to the actual session
    state.
  • JSONL + SQLite SSE 双通道联动，让 HUD 尽量贴近真实会话状态。
• 💸 Cached Token Discount, calculated correctly
  • Model-aware pricing includes cached-input discounts, output, and reasoning
    tokens.
  • 支持模型感知定价，准确处理 cached input 折扣、输出 token 和推理 token。
• 🧩 Zero Dependency
  • Pure Python standard library, easy to audit and easy to ship.
  • 纯 Python 标准库，实现可审计、可分发、无额外依赖。
• 🖥️ Cross-platform HUD
  • Windows / macOS / Linux path discovery, active-session tracking, docking,
    drawer expansion, and auto-scroll marquee behavior.
  • 支持 Windows / macOS / Linux 的路径发现、活动会话跟踪、吸附、抽屉展开
    和长文本滚动动效。
• 🧪 Regression locked
  • 39 unit tests pin the parser, pricing, platform adapters, active session
    logic, and UI behavior.
  • 39 项单元测试锁死解析、计费、平台适配、活动会话逻辑与 UI 行为。

⚠️ PRIVACY WARNING

Do not submit raw Codex JSONL logs, raw SQLite databases, or unredacted
prompts/responses.

If you need help, share only minimal redacted snippets or synthetic repro
data.

严禁提交原始日志。
如果需要协助，请只提供最小化、脱敏后的片段，或自造的复现样例。

See docs/PRIVACY.md for the full redaction rules.

🧭 What changed in this alpha / 本次 Alpha 有什么

• From a single-file prototype to a structured src/ package with core/,
  platforms/, and ui/ layers.
• Built a resilient JSONL parser that tolerates partial trailing writes and
  keeps working on live session files.
• Added a read-only SQLite SSE state machine to follow live request creation,
  progress, and completion without locking local databases.
• Added active conversation discovery so the HUD can follow the current Codex
  session more naturally.
• Added smart docking, expanded detail drawers, draggable windows, and animated
  long-text/numeric transitions to the Tk HUD.

📚 Reference / 参考

• Changelog: CHANGELOG.md
• Privacy policy: docs/PRIVACY.md