ClaudexBar
ipangdz/claudexbar
Monitore limites Codex e Claude Code direto na barra de menu do macOS
Ver no GitHubApp nativo de menu bar para macOS que monitora em tempo real os limites de uso do Codex e Claude Code. Zero configuração: reutiliza sua autenticação CLI existente, mostra janelas de sessão (5h) e semanal, e alerta antes de acabar o crédito.
Instalação
npx convez-ai ipangdz/claudexbar1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Acompanhar consumo de quotas Codex e Claude Code em tempo real
- Receber alertas antes de esgotar limites de uso
- Gerenciar múltiplos provedores de código IA em uma interface unificada
Veredito

Solução minimalista e bem executada para quem usa Codex ou Claude Code no macOS. Autenticação zero-config reutiliza credenciais existentes, sem dependências externas — prático para desenvolvedores que querem monitorar quotas sem sair da barra de menu.
README
A tradução para o português deste README ainda está na fila.
A small native macOS menu-bar app that shows Codex and Claude Code usage limits at a glance. Zero-config: it reuses your existing CLI login, shows each provider's session (5-hour) and weekly windows, and warns before you run low — no API keys, no browser cookies, no dependencies.
Demo
Features
- Native AppKit menu bar app with no Dock icon and no main window.
- Two providers only: Codex and Claude Code.
- Codex auth from
~/.codex/auth.json. Claude Code auth from a ClaudexBar-managed OAuth credential in Keychain (ClaudexBar-Claude-Credentials), falling back toCLAUDE_CODE_OAUTH_TOKENand Claude Code's ownClaude Code-credentialslogin. - Re-auth: Codex opens
codex loginin Terminal; Claude Code opens your browser to Claude's sign-in page. After you approve, Claude shows a one-time code — paste it into the ClaudexBar dialog and it stores its own access+refresh credential (no Terminal). - Configurable refresh interval and remaining-usage notifications.
- No telemetry, analytics, or browser cookies. The only value you paste is the one-time Claude authorization code, which is exchanged for a token and never stored.
Install
Works on both Apple Silicon and Intel Macs (macOS 13+).
Homebrew (prebuilt)
brew install --cask ipangdz/tap/claudexbar
A universal, prebuilt .app — no toolchain required.
From source (one line)
Builds a native binary for your machine; needs the Xcode Command Line Tools (xcode-select --install), which provide git and the Swift toolchain.
curl -fsSL https://raw.githubusercontent.com/ipangdz/claudexbar/main/scripts/install.sh | bash
Or from a checkout:
git clone https://github.com/ipangdz/claudexbar.git && cd claudexbar
./scripts/install.sh
Either way, the installer builds the release binary, assembles ~/Applications/ClaudexBar.app (with its icon), ad-hoc code-signs it, installs ~/.local/bin/claudexbar, writes a LaunchAgent, and starts it. To update later, just run the one-liner again.
Because it builds from source on your own machine, no Apple Developer account, certificate, or notarization is required. (A prebuilt, notarized .dmg would need an Apple Developer ID — a possible future option.) The app is a menu-bar accessory (LSUIElement), so its icon appears in Finder/Spotlight rather than the Dock.
Development
swift build
swift run ClaudexBarTestRunner
ClaudexBarTestRunner covers reset-label formatting, live countdown rendering, Codex and Claude response parsing, notification threshold decisions, one-notification-per-window-cycle deduping, and cross-provider hints.
Uninstall
./scripts/uninstall.sh
Uninstall removes the ClaudexBar binary, LaunchAgent, app settings, and logs. It does not touch Codex or Claude Code credentials.
Usage
ClaudexBar can switch providers automatically: when both providers are enabled, it watches lightweight local context (foreground app/window text and recent Codex/Claude session-file activity) and switches only after one provider has been the clear winner for a short debounce window. It does not use CPU usage or shell process scans as deciding signals.
Left-click the pill to cycle between enabled providers. Manual clicks still work in auto mode and temporarily pin your choice so the pill does not jump around while you move between tools. If only one provider is enabled, left-click leaves that provider selected. Right-click for the menu.
The right-click menu lists each provider once, as a 1-click checkbox row:
- The checkbox toggles whether the provider is enabled (Codex + Claude Code both checked → left-click cycles between them; only one checked → ClaudexBar stays on it). At least one provider always stays enabled.
- The row shows that provider's live usage (
5h% · 7d%), or a status word (auth/net/err) when there is a problem. - Hold ⌥ Option (the menu reacts live): each provider row turns into Re-auth Codex / Re-auth Claude Code, and Refresh All turns into Open Logs….
Below the providers are Refresh All, Smart Auto Switch, Launch at Login, Refresh Interval, and Notify When Remaining.
The left usage column is the current session window. The right column is the weekly budget. Session usage also chips away at the weekly budget.
Troubleshooting
-
authfor Codex: runcodex login. -
authfor Claude Code: chooseRe-auth→Claude Codefrom the ClaudexBar menu. Your browser opens to Claude's sign-in page (claude.com/cai/oauth/authorize). Approve access; Claude's callback page then shows a one-timecode#statestring. Copy it and paste it into the ClaudexBar dialog (it pre-fills from your clipboard when it recognises a code). ClaudexBar exchanges it for an access+refresh credential — with the full scopes the usage endpoint needs — stored in the Keychain serviceClaudexBar-Claude-Credentials, then refreshes usage. The code and tokens are never logged. -
Why a paste (and not a fully automatic flow): Claude's OAuth client does not accept a
localhostredirect, so the authorization code is returned to Claude's own callback page rather than to ClaudexBar directly. The one paste bridges that page back to the app. -
Why a separate credential: Claude Code's own
Claude Code-credentialslogin rotates its refresh token on every refresh, so a background menu-bar app reading that snapshot would be invalidated whenever Claude Code refreshes (and vice versa). ClaudexBar runs its own OAuth sign-in to get an independent credential it refreshes on its own (the access token lasts ~8 hours and is refreshed automatically). -
loginstuck in the pill: the code exchange is still running or failed. Checkauthafterwards and re-runRe-auth→Claude Code. -
authright after re-auth: the paste may have been incomplete. Re-run and paste the entirecode#statestring from Claude's page. -
If you want terminal Claude Code sessions to use a manually generated token too, set:
export CLAUDE_CODE_OAUTH_TOKEN='<token>' -
Claude
err/HTTP 403: the stored credential lacks a required scope. RunRe-auth→Claude Codeagain — ClaudexBar requests the correct scope set itself. (Note:claude setup-tokenis not used; its token has too narrow a scope for the usage endpoint. See docs/AUTH.md.) -
net: the usage endpoint could not be reached or may be rate limited. Use the provider'sRefreshfrom the menu a little later.
Non-goals
- No history graphs.
- No cost estimation.
- No embedded/in-app web view: sign-in happens in your real browser via the official CLI.
- No additional providers in MVP.
Documentation
- docs/AUTH.md — how Codex and Claude Code authentication work, and why.
- SECURITY.md — security model and how to report a vulnerability.
- CHANGELOG.md — release notes.
Contributing
Contributions are welcome — see CONTRIBUTING.md. The project is deliberately narrow (Codex + Claude Code only) and dependency-free.
License
MIT.