Linux tray indicator for monitoring OpenAI Codex usage limits.
CodexTray keeps your active Codex quota visible from the Ubuntu/GNOME system tray. It reuses your existing local Codex authentication, displays weekly usage and reset timing, and offers an optional privacy-first dashboard.
Highlights
- Compact tray indicator with the remaining quota percentage
- Terminal-inspired dashboard for weekly usage and reset credits
- Account email masked by default and revealed only on click
- Explicit confirmation before consuming a limit reset credit
- Background refresh every five minutes without blocking the GTK UI
- Low-quota desktop notification at 20% remaining
- Optional login autostart
- No telemetry, analytics, or bundled credentials
| Dashboard | Tray menu |
|---|---|
 |
 |
Download the latest .deb from GitHub Releases, then install it with APT:
sudo apt install ./codex-tray_0.1.1_amd64.debLaunch CodexTray from the applications menu or run:
codex-trayOpen the dashboard directly with:
codex-tray --dashboard- Ubuntu/Debian on
amd64 - Python 3
- GTK 3 and PyGObject
- Ayatana AppIndicator bindings
- Codex CLI installed and signed in
The Debian package declares its Linux UI dependencies, so APT installs them automatically.
- Sign in using the official Codex CLI.
- Start CodexTray.
- Click the tray icon to inspect usage or open the dashboard.
- Enable Start automatically if desired.
- If reset credits are available, select reset now and confirm the action.
For a one-shot diagnostic:
codex-tray --onceCodexTray is designed to keep account data local:
- It does not collect telemetry or send data to a project-owned server.
- It does not embed API keys, access tokens, passwords, or account details.
- It reuses credentials already managed by Codex/CodexBar on the local machine.
- The email shown in the dashboard is masked by default.
- Provider requests run in a worker thread and have a bounded timeout.
- Limit reset consumption requires an explicit confirmation dialog.
- The pinned CodexBar CLI download is verified with SHA-256 before packaging.
See SECURITY.md for vulnerability reporting and the security model.
git clone https://github.com/andreimironstv/CodexTray.git
cd CodexTray
/usr/bin/python3 -m unittest discover -s tests -v
/usr/bin/python3 scripts/build_deb.pyThe build downloads the pinned CodexBar CLI release from its official GitHub repository and verifies this checksum before extraction:
8f5f6f5b492832fbc7d463abc6abd7fbbc28edc7bd5a93bfb08e52dda325c896
The resulting installer is written to:
dist/codex-tray_0.1.1_amd64.deb
Validate it locally with:
desktop-file-validate assets/codex-tray.desktop
dpkg-deb --info dist/codex-tray_0.1.1_amd64.deb
dpkg-deb --contents dist/codex-tray_0.1.1_amd64.deb
apt-get -s install ./dist/codex-tray_0.1.1_amd64.debcodex_tray/core.py Parsing, formatting, quota selection, reset RPC
codex_tray/app.py GTK/AppIndicator UI and background refresh workers
scripts/build_deb.py Reproducible Debian package assembly
assets/ Desktop entry, tray icons, and application artwork
tests/ Dependency-free unit tests for core behavior
Usage fetching is delegated to the pinned, MIT-licensed CodexBar CLI. CodexTray requests only the Codex provider and parses its JSON response. The provider binary is downloaded during packaging rather than committed to this repository.
Contributions are welcome. Please read CONTRIBUTING.md, add tests for behavior changes, and ensure the full test suite passes before opening a pull request.
The packaged application includes the CodexBar CLI provider engine, pinned to v0.44.0 and distributed under its MIT license. Its license text is included at vendor/CODEXBAR_LICENSE and installed with the package.
CodexTray is an independent community project and is not affiliated with or endorsed by OpenAI.
CodexTray is released under the permissive MIT License.