codex-quota-linux

Minimal Linux AppIndicator for monitoring and switching Codex account quota.

This is an unofficial personal utility, not an OpenAI or Codex project. It depends on unstable Codex internal API surfaces, may break without notice, and is not guaranteed to be maintained promptly.

This project is distributed as source code only. Clone the repository and use the ./codex-quota launcher; wheel and sdist packages are not published or supported.

Requirements

• Linux desktop with AppIndicator support
• codex CLI available on PATH
• Python 3.10+
• Python GTK and Ayatana AppIndicator bindings from your Linux distribution

The project was developed on Ubuntu 22.04 with Codex Desktop Linux. Other distributions are untested.

Check local dependencies with:

./codex-quota doctor

Features and usage

Monitor quota

Show the current account's 5-hour and longer-term quota in the Linux top bar, with all saved accounts available in the tray menu.

./codex-quota once
./codex-quota run

once prints a terminal snapshot. run starts the tray indicator and is also the default command when no subcommand is provided.

Check reset credits

Show reset-credit counts and available details in the tray menu or terminal.

./codex-quota check-reset-credits
./codex-quota check-reset-credits --all
./codex-quota check-reset-credits --alias Personal --alias Work

Switch saved accounts

Add Codex accounts under local aliases, then switch the main Codex login explicitly.

./codex-quota add Personal
./codex-quota add Work
./codex-quota switch Work

The tray menu provides the same switch action. Running Codex applications may need to be restarted after switching.

If a quota or reset-credit query finds that a saved slot is no longer authenticated, the project can copy a newer main Codex credential into that slot only when the account matches, then retry the direct query once. Older or different-account credentials are ignored, and query recovery never replaces the main Codex login.

Activate quota windows

Send a tiny Codex request under selected saved accounts to activate their rolling quota windows. This may use a small number of tokens.

./codex-quota activate-window --alias Personal
./codex-quota activate-window --all
./codex-quota activate-window --all --dry-run

Configuration

Configuration is stored in .runtime/config.toml and is created on first run.

selected_alias = ""
quota_active_refresh_interval_seconds = 120
quota_standby_refresh_interval_seconds = 600
direct_max_attempts = 3
direct_timeout_seconds = 8
activate_timeout_seconds = 90
reset_credits_refresh_interval_seconds = 86400

Restart the tray process after changing refresh intervals. See Architecture and runtime behavior for refresh triggers, fallback behavior, caching, and GUI state rules.

Local data and security

Project-local runtime data lives in the git-ignored .runtime/ directory:

• .runtime/config.toml: selected account and configuration.
• .runtime/accounts/<Alias>/auth.json: saved account credentials.
• .runtime/accounts/<Alias>/cache.json: latest quota snapshot.
• .runtime/accounts/<Alias>/reset_credits_cache.json: latest reset-credit snapshot.
• .runtime/tmp/codex-homes/: short-lived isolated Codex homes.

Treat the entire .runtime/ directory as secret. See the security policy for the security boundary and vulnerability reporting policy.

Publishing safely

Do not upload an archive of the whole checkout. This source-only project should be published from reviewed, tracked Git files.

Enable the optional pre-commit guard once per clone:

git config core.hooksPath .githooks

Run the same public-tree check manually:

python3 scripts/check_public_tree.py

By default, this checks both working-tree files and staged blobs. The pre-commit hook uses the staged-only --cached mode.

The guard reduces accidental credential publication, but does not replace reviewing git status and the final tracked tree.

Development

The implemented data flows and user-visible behavior are documented in docs/architecture.md.

Run the test suite with:

python3 -m unittest discover -s tests

License

MIT