Skip to main content
CodexBar is available for macOS 14+ (Sonoma) and Linux (CLI only).

​
System Requirements

CodexBar requires macOS 14 (Sonoma) or later for the full menu bar application.
For Linux users, the CLI-only version is available via Homebrew or GitHub Releases.

​
Installation Methods

brew install --cask steipete/tap/codexbar
Linux support is provided via the CLI and includes community integrations for Waybar modules and TUI interfaces.

​
Installing the CLI (macOS)

The CodexBar CLI allows you to query usage data from scripts, CI pipelines, or terminal dashboards.
1

Install via the App

Open CodexBar → Preferences → Advanced → Install CLIThis symlinks the CLI helper to /usr/local/bin/codexbar and /opt/homebrew/bin/codexbar.
2

Verify Installation

codexbar --version
3

Test Usage Query

codexbar usage --format json --pretty

​
Manual CLI Installation

If you prefer to install the CLI manually: 
ln -sf "/Applications/CodexBar.app/Contents/Helpers/CodexBarCLI" /usr/local/bin/codexbar

​
Building from Source

Developers can build CodexBar directly from the repository.
1

Clone the Repository

git clone https://github.com/steipete/CodexBar.git
cd CodexBar
2

Build the Application

swift build -c release
./Scripts/package_app.sh
3

Launch the App

open CodexBar.app
For active development, use the quick dev loop script:
./Scripts/compile_and_run.sh
This script builds, tests, packages, and relaunches CodexBar automatically.

​
System Permissions

CodexBar requires certain permissions to access provider data from various sources.

​
Full Disk Access (Optional)

Only required if you want to read Safari cookies/local storage for web-based providers (Codex web, Claude web, Cursor, Droid/Factory).
If you don’t grant Full Disk Access, you can still use:
  • Chrome/Firefox cookies
  • CLI-only authentication sources
  • OAuth flows
  • API tokens
To grant Full Disk Access:
1

Open System Settings

Navigate to System Settings → Privacy & Security → Full Disk Access
2

Add CodexBar

Click the + button and select CodexBar.app from Applications
3

Restart CodexBar

Quit and relaunch CodexBar for the permission to take effect

​
Keychain Access

CodexBar may prompt for keychain access to:
  • Decrypt Chrome/Brave/Edge cookies (“Chrome Safe Storage” key)
  • Read Claude OAuth credentials (stored by Claude CLI)
  • Store API tokens for z.ai, Copilot, and other providers
Prevent repeated keychain prompts:
  1. Open Keychain Access.app
  2. Search for the item (e.g., “Chrome Safe Storage” or “Claude Code-credentials”)
  3. Double-click the item → Access Control tab
  4. Add CodexBar.app under “Always allow access by these applications”
  5. Save and relaunch CodexBar

​
Files & Folders Access

CodexBar may request folder access when launching provider CLIs that read project directories or external drives. This is driven by the CLI’s working directory, not background scanning.
CodexBar does not request:
  • Screen Recording
  • Accessibility
  • Automation permissions

​
Next Steps

Quick Start

Configure providers and start monitoring your usage

CLI Reference

Learn how to use the command-line interface

Build docs developers (and LLMs) love

Get started for freeTalk to us