Skip to main content

​
First run setup

After installing CodexBar, follow these steps to configure your providers and start tracking usage.
1

Open Settings

Launch CodexBar and click the menu bar icon, then select Settings (or press ⌘,).Navigate to Settings → Providers to see all available AI coding assistants.
2

Enable your providers

Toggle on the providers you actively use:
  • Codex (OpenAI)
  • Claude Code
  • Cursor
  • Gemini
  • Copilot
  • And 10+ more providers
Each enabled provider appears as a separate menu bar icon by default. You can combine them using Merge Icons mode in Settings.
3

Configure authentication

Install and sign in to the provider sources you rely on:
  • CLI tools: codex, claude, gemini, etc.
  • Browser cookies: Safari, Chrome, or Firefox sessions
  • OAuth: Direct API authentication
For Codex web dashboard extras, go to Settings → Providers → Codex → OpenAI cookies and choose Automatic or Manual import.
CodexBar reuses your existing authentication. No passwords are stored.

​
Provider-specific setup

Different providers require different authentication methods. Choose your provider below for detailed setup instructions.

​
Codex (OpenAI CLI)

Prerequisites:
  • Install the Codex CLI: npm install -g @openai/codex-cli
  • Authenticate: codex auth
Optional: Web DashboardFor enhanced metrics (code review remaining, usage breakdown, credits history):
  1. Go to Settings → Providers → Codex
  2. Under OpenAI cookies, select Automatic (reads Safari/Chrome/Firefox) or Manual (paste session cookie)
  3. Grant Full Disk Access if using Safari cookies
Verify it works:
codexbar --provider codex

​
Understanding the menu bar icon

CodexBar displays usage with a two-bar meter:
  • Top bar: Session or 5-hour window usage (0–100%)
  • Bottom bar: Weekly window usage (thin hairline, 0–100%)
Visual indicators:
  • Dimmed icon: Data is stale or an error occurred
  • Status overlay: Service incident detected
  • Thicker top bar: Credits remaining (when weekly is exhausted)
Click the icon to see detailed metrics:
  • Session percentage and reset countdown
  • Weekly percentage and reset countdown
  • Credits remaining (where applicable)
  • Account info and plan details

​
Using the CLI

CodexBar includes a powerful CLI for scripting and CI pipelines.
1

Install the CLI

In the app: Settings → Advanced → Install CLIOr manually:
ln -sf "/Applications/CodexBar.app/Contents/Helpers/CodexBarCLI" /usr/local/bin/codexbar
2

Run commands

Check usage:
codexbar
# or specify provider
codexbar --provider claude
JSON output:
codexbar --format json --pretty
Cost tracking:
codexbar cost --provider codex
All providers:
codexbar --provider all
See CLI documentation for complete command reference.

​
Customizing settings

​
Merge Icons mode

Combine all providers into a single menu bar icon:
  1. Go to Settings → General
  2. Enable Merge Icons
  3. Click the unified icon to switch between providers
  4. Enable Overview tab to see up to 3 providers at once

​
Refresh cadence

Control how often CodexBar checks for updates:
  • Manual: Click to refresh
  • 1m, 2m, 5m, 15m: Automatic refresh intervals
  • 30m: Battery-friendly option

​
Reset time display

Choose how reset times are shown:
  • Countdown: “Resets in 3h 24m”
  • Absolute: “Resets at 2:15 PM”
  • Relative: “Resets tomorrow at 1:00 AM”

​
Privacy and security

CodexBar is privacy-first:
  • On-device parsing: All data processing happens locally
  • No passwords stored: Reuses existing CLI and browser auth
  • Opt-in cookies: Browser cookie access requires your permission
  • Minimal access: Only reads known locations (no filesystem crawling)
  • Open source: Auditable at github.com/steipete/codexbar
See Privacy documentation for details.

​
Troubleshooting

To stop repeated Keychain prompts:
  1. Open Keychain Access.app
  2. Search for the credential (e.g., “Chrome Safe Storage” or “Claude Code-credentials”)
  3. Open the item → Access Control
  4. Click + and add CodexBar.app
  5. Save and relaunch CodexBar
See Permissions guide for detailed instructions with screenshots.
Full Disk Access is only needed for Safari cookies. Alternatives:
  • Use Chrome or Firefox cookies instead (no FDA required)
  • Use CLI-only authentication (no browser cookies)
  • Use OAuth where supported (Claude, Gemini, Copilot)
This can happen if:
  • Session expired: Re-authenticate with the provider CLI or browser
  • API changed: Check for CodexBar updates
  • Wrong account: Verify you’re logged in to the correct account
Try forcing a specific source:
codexbar --provider codex --source web
codexbar --provider claude --source oauth

​
Next steps

Explore providers

Learn about all 15+ supported AI coding assistants

CLI reference

Use CodexBar in scripts and CI pipelines

Configure settings

Customize refresh cadence, display options, and more

Build from source

Contribute or build your own custom version

Build docs developers (and LLMs) love

Get started for freeTalk to us