Codex Minibar

Free, open-source Windows tray companion for AI subscription usage limits with configurable tray widgets, a compact usage popup, notifications, auto-start, in-place updates, and local history.

Download | Website | Issues

---

Overview

Codex Minibar reads quota data from locally authenticated provider sessions and keeps subscription limits and reset times visible in the notification area. It is a native WinUI 3 application written in Rust.

Codex Minibar is an independent project. It is not affiliated with, endorsed by, or sponsored by OpenAI.

Features

• Show five-hour and weekly usage in one or more configurable tray icons.
• Choose numbers, bars, rings, reset times, or reset countdowns; show remaining or used percentage as appropriate.
• Open a compact native popup for the current plan, credits, limit windows, and local token statistics (today, the configured history window, and a compact activity bar chart).
• Receive Windows notifications when a limit resets, usage becomes low, Codex cannot be reached, or an update is available.
• Receive announced Codex forced-reset countdowns from the public GitHub feed. The feed contract and bot update rules live in docs/codex-resets-feed.md.
• Optionally start Codex automatically to activate a fresh five-hour window.
• Configure planned limit activations and provider-specific quiet periods for automatic activation, such as keeping a work Claude session inactive on weekends.
• Use the optional Stream Deck companion to place independently configured quota indicators on hardware keys, open the popup or a provider tab, and launch Minibar on click when it is not running.
• Start with Windows, update in place from GitHub Releases, and retain history locally.
• Detect Codex installations automatically, with an override for a custom executable path.
• Enable Codex, Claude, Cursor, OpenCode Zen, OpenCode Go, OpenRouter, Antigravity, and Grok independently in Settings → Providers. Providers refresh independently; Antigravity and Grok show subscription quota rather than unrelated API billing.

Requirements

• Windows 10 or Windows 11 (64-bit ARM or x64).
• A locally installed and authenticated supported provider, or an OpenRouter API key.

The app does not copy provider credentials into its ordinary settings file. It talks to the local Codex app server, reads Claude Code's existing local OAuth session, reads OpenCode's local configuration/history, reuses the official Antigravity or Grok CLI sign-in, or requests OpenRouter key usage. Optional OpenCode and OpenRouter manual API keys are protected with Windows user-scoped DPAPI storage. The app stores its own settings and usage history in your Windows user profile.

For Antigravity, run agy and complete its normal sign-in once; Minibar reads that existing Windows Credential Manager session and never stores it in app settings. For Grok, run grok login; Minibar reads the official CLI auth cache. If either session expires, refresh it in the official CLI. Browser-session access is not used.

Install

1. Open the latest release.
2. Download the installer matching your Windows architecture (x64 or arm64) and run it. The installer is per-user and does not require administrator rights.
3. Alternatively, download the matching portable.zip, extract it, and run codex-minibar.exe.
4. Find the icon in the notification area. If it is hidden, Windows may have tucked it under the ^ overflow menu, because apparently that is where delightful UX goes to die.

On first run, Codex Minibar discovers Codex automatically. Open Settings from the tray menu if you need to choose another executable or adjust the tray widgets and notifications.

Updating

By default, Codex Minibar checks GitHub Releases for updates and can install a matching portable package in place. You can disable update checks in Settings at any time.

Build from source

Install the Rust toolchain pinned in rust-toolchain.toml, then run:

cargo check --locked
cargo test --all-targets --all-features --locked
cargo clippy --all-targets --all-features --locked -- -D warnings

To build distributable Windows packages, run:

.\build.ps1

This produces architecture-specific portable ZIP files and NSIS installers under dist/.

Development

The UI uses windows-reactor with WinUI 3; the Windows App SDK 2.4.0 runtime is bundled through windows-reactor-setup self-contained deployment. CI checks formatting, lints, and tests on Windows.

Stream Deck companion

The optional companion lives in streamdeck/. It stores each key's configuration in Stream Deck and reads sanitized quota snapshots from the running Minibar process over loopback. With Node.js 24+ installed, build and package it with:

Each key can be configured as a single-limit ring for 5h or Weekly, with a custom reset display, or as a combined 5h + Weekly widget.

cd streamdeck
npm install
npm run build
npx @elgato/cli@latest validate .\com.vertopolkalf.codex-minibar.sdPlugin
npx @elgato/cli@latest pack .\com.vertopolkalf.codex-minibar.sdPlugin

The resulting .streamDeckPlugin file can be opened with Stream Deck Desktop.

Bug reports and focused pull requests are welcome. Please include your Windows version, Codex installation type, and clear reproduction steps when reporting a problem.

Contributing

We especially need help supporting the many different providers people use. Provider APIs, local data formats, authentication flows, and quota semantics all vary, so testing integrations with real provider accounts and keeping them working over time is particularly valuable.

To contribute:

1. Fork the repository and create a focused branch.
2. Make the smallest change that solves the problem.
3. Run the relevant checks from Build from source.
4. Open a pull request with a clear description, reproduction steps, and provider-specific setup details when applicable.

For provider changes, include sanitized sample data or fixtures when possible. Never commit credentials, tokens, or personal usage history.

License

Licensed under the Apache License, Version 2.0.