CodexBar Lite

Product Introduction

1. Definition: CodexBar Lite is a native macOS menu bar application (a lightweight, single-purpose utility) designed to monitor OpenAI Codex usage and rate-limit reset timers in real-time. It operates as a passive tracker, reading from the local Codex CLI session file.
2. Core Value Proposition: It exists to provide developers and power users with a zero-friction, privacy-respecting way to monitor their OpenAI Codex API consumption directly from the macOS menu bar. Its primary value is delivering critical usage data at a glance without requiring browser extensions, API key management, or intrusive system permissions.

Main Features

1. Native Menu Bar Integration: The app runs as a lightweight process in the macOS system menu bar, displaying Codex usage as a percentage or credits remaining. Clicking the menu bar item reveals a detailed dropdown with primary/secondary usage, reset timers, and last update time. It is built using Swift for optimal macOS integration and performance.
2. Session-Based Authentication (No API Key): CodexBar Lite works by reading the existing authentication token from ~/.codex/auth.json, a file created and managed by the official codex login CLI command. It uses this session to make direct, authenticated requests to chatgpt.com's usage endpoint. This eliminates the need for users to manually manage or expose API keys.
3. Configurable Notifications & Preferences: Users receive native macOS notifications at configurable usage thresholds (80%, 90%, exhaustion, and credit reset). The app includes a preferences pane to set the refresh interval (e.g., every 5 minutes), choose between displaying "percentage used" or "percentage remaining," enable launch at login, and manage automatic updates via the Sparkle framework.

Problems Solved

1. Pain Point: Manually checking Codex usage is inefficient. Developers must either run a CLI command (/status) or open a web browser to navigate to the usage dashboard, interrupting their workflow. There is no proactive warning before hitting rate limits.
2. Target Audience: The primary audience is software developers, engineers, and technical professionals who use the OpenAI Codex CLI or API extensively in their daily workflow, particularly those on Apple Silicon Macs running macOS Ventura or later. This includes full-stack developers, AI engineers, and DevOps practitioners.
3. Use Cases: Essential for developers during intensive coding sessions with Codex to avoid unexpected "credit exhausted" interruptions. It is also critical for team leads or individuals managing tight API budgets, allowing them to monitor consumption passively and plan usage around reset schedules.

Unique Advantages

1. Differentiation: Unlike multi-provider trackers like the original CodexBar (which requires browser cookie or Keychain access), CodexBar Lite is single-purpose. This focused scope allows it to operate with dramatically reduced permissions—it never requests Keychain, Full Disk Access, or browser profile permissions, setting a higher privacy standard.
2. Key Innovation: Its architecture is based on leveraging the existing official Codex CLI session. This is a novel approach that bypasses the complexity and security concerns of scraping browser cookies or managing API keys. The innovation is in achieving full functionality through minimal, system-native access (~/.codex/auth.json and network requests to OpenAI).

Frequently Asked Questions (FAQ)

1. Is CodexBar Lite safe to use? Does it access my browser or passwords? Yes, it is designed with a security-first approach. CodexBar Lite only reads the ~/.codex/auth.json session file and makes network requests to chatgpt.com. It does not access your macOS Keychain, browser cookies, browser profiles, or any other sensitive data. The source code is open for audit on GitHub.
2. How does CodexBar Lite get my usage data without an API key? It uses the session authentication already established by the official codex login command. The app reads the token from the local auth.json file and uses it to query OpenAI's usage endpoint directly, identical to how the Codex CLI itself operates, eliminating the need for a separate API key.
3. What happens if I haven't logged into the Codex CLI yet? Upon first launch, if CodexBar Lite detects no valid auth.json file, it will automatically open the Terminal and execute the codex login command for you. It then monitors for the command's completion and will begin displaying usage once you have successfully authenticated.
4. Can I use CodexBar Lite on an Intel Mac or an older version of macOS? No. CodexBar Lite is currently compiled exclusively for Apple Silicon (arm64) Macs and requires macOS 13 (Ventura) or later. This allows it to leverage modern macOS frameworks and optimize for the current architecture.
5. How do I update or uninstall CodexBar Lite? The app includes a "Check for Updates..." menu item using the Sparkle framework. To uninstall completely, quit the app, drag it from /Applications to Trash, and optionally delete its support files (~/Library/Application Support/CodexBarLite) and preferences (defaults delete dev.vaibhav.codexbar).