Skip to content

README.md

Latest commit

 

History

History
84 lines (61 loc) · 2.71 KB

README.md

File metadata and controls

84 lines (61 loc) · 2.71 KB
Raw

Codex Usage Widget

繁體中文

Developer documentation: Architecture

Always-on-top desktop widget for monitoring Codex usage limits through the Codex app-server.

Features

  • Reads Codex usage limits through codex app-server.
  • Shows remaining percentage, reset time, and credits in an always-on-top widget.
  • Supports Traditional Chinese and English. The default language follows the system language; unsupported languages fall back to English.
  • Supports system theme, Tiffany Blue light theme, and Monokai dark theme.
  • Supports panel opacity from 0% to 100%, defaulting to 75%.
  • Double-click the panel to minimize it to the system tray.
  • The tray icon renders the primary remaining usage, and its tooltip shows the remaining usage.
  • Double-click the tray icon to restore the always-on-top panel. The tray context menu also includes show and close actions.
  • Shuts down cleanly by cancelling pending Tk callbacks before destroying the window.

Requirements

  • Python 3.13+
  • uv
  • Codex CLI with codex app-server support
  • A desktop environment with system tray support

Installation

Install from GitHub:

uv tool install git+https://github.com/codemee/codex_usage.git

Install from a local checkout:

uv tool install .

Run

codex-usage-widget

Development

git clone https://github.com/codemee/codex_usage.git
cd codex_usage
uv sync
uv run codex-usage-widget
uv run python -m unittest discover -s tests

codex must be available on PATH and authenticated before the widget can read usage data. The project currently uses a single application module; see the architecture document for component boundaries, data flow, threading rules, and extension guidance.

Project structure

codex_usage_widget.py   Application, app-server client, parsing, UI, and tray integration
tests/                  Unit and Tk layout tests
docs/                   Developer architecture documentation
pyproject.toml          Package metadata, dependencies, and CLI entry point
prd.md                  Product requirements implemented by the widget

Usage

  • Drag empty panel space or usage cards to move the widget.
  • Use the top ◎ / 文 / A button to cycle language modes: system, Traditional Chinese, English.
  • Use the top ◐ / ☀ / ☾ button to cycle theme modes: system, light, dark.
  • Use the top slider to adjust panel opacity.
  • Right-click the panel to refresh now, reconnect, or close.
  • Double-click the panel to minimize it to the system tray.
  • Double-click the tray icon to restore the always-on-top panel.

Tests

uv run python -m unittest discover -s tests