How to Install steipete/CodexBar on macOS and Linux

You can install CodexBar via Homebrew Cask on macOS, download pre-built binaries from GitHub Releases for macOS and Linux, or install the bundled CLI helper after setting up the UI app.

CodexBar is a lightweight menu-bar application for macOS 14+ that tracks AI-coding quota usage across multiple providers. The repository at steipete/CodexBar distributes both a graphical UI app and a command-line interface (CLI), with installation methods varying by platform and use case.

Installation Methods Overview

CodexBar supports three primary installation paths depending on your operating system and whether you need the menu-bar UI or just the CLI:

• Homebrew Cask (macOS only): Installs the signed UI app (CodexBar.app) to /Applications
• GitHub Releases (macOS and Linux): Provides universal macOS zips and architecture-specific CLI tarballs
• Bundled CLI Installer (macOS only): Creates symlinks to the CLI helper embedded within the UI app bundle at /Applications/CodexBar.app/Contents/Helpers/CodexBarCLI

Install CodexBar on macOS

Using Homebrew Cask (Recommended)

The fastest way to install CodexBar on macOS is through the official Homebrew Cask. This method disables Sparkle auto-updates to ensure version management remains controlled through Homebrew.

brew install --cask codexbar

After installation completes, launch the app:

open -a CodexBar

According to the Homebrew release playbook at docs/releasing-homebrew.md, the cask downloads CodexBar-macos-universal-<version>.zip from GitHub Releases and extracts it to /Applications. The build process specifically disables Sparkle updates for Homebrew installs, routing update notifications to use brew upgrade instead.

Manual Installation from GitHub Releases

If you prefer not to use Homebrew, download the universal binary directly from the releases page:

# Download the latest universal build

curl -L -o CodexBar.zip \
  https://github.com/steipete/CodexBar/releases/latest/download/CodexBar-macos-universal.zip

# Extract and move to Applications

unzip CodexBar.zip
mv CodexBar.app /Applications/
open -a CodexBar

Installing the Bundled CLI Helper

Once the UI app resides in /Applications, you can expose the codexbar command-line tool to your system PATH using the provided installer script in bin/install-codexbar-cli.sh:

# From the cloned repository or downloaded source

./bin/install-codexbar-cli.sh

This script uses AppleScript (osascript) to request administrative privileges, then creates symbolic links at standard binary locations defined in the script's TARGETS variable—specifically /usr/local/bin/codexbar and /opt/homebrew/bin/codexbar—pointing to /Applications/CodexBar.app/Contents/Helpers/CodexBarCLI.

Verify the installation by checking the version:

codexbar version

Install CodexBar CLI on Linux

Linux users can only install the CLI component, as the menu-bar UI requires macOS 14+. The GitHub Releases page provides four architecture-specific tarballs:

Asset	Architecture
CodexBarCLI-v<tag>-linux-x86_64.tar.gz	x86_64
CodexBarCLI-v<tag>-linux-aarch64.tar.gz	ARM64

Download and extract the appropriate binary for your system:

# Example for x86_64 Linux

curl -L -o codexbar.tar.gz \
  https://github.com/steipete/CodexBar/releases/latest/download/CodexBarCLI-v<version>-linux-x86_64.tar.gz

sudo tar -xzf codexbar.tar.gz -C /usr/local/bin
codexbar usage

Post-Installation Setup

After installation, configure CodexBar to track your AI provider usage. The application stores resolved configuration at ~/.config/codexbar/config.json (modern installs) or ~/.codexbar/config.json (legacy).

1. Launch the app (open -a CodexBar) or run the CLI
2. Navigate to Settings → Providers in the UI or use CLI commands
3. Enable desired providers:

# List available providers

codexbar config providers

# Enable specific providers

codexbar config enable --provider grok
codexbar config enable --provider cursor

# Store API keys securely (example for ElevenLabs)

printf '%s' "$ELEVENLABS_API_KEY" | \
  codexbar config set-api-key --provider elevenlabs --stdin

The UI app (Sources/CodexBar) and CLI (Sources/CodexBarCLI) share the same underlying state management through UsageStore and SettingsStore, ensuring synchronized configuration regardless of which interface you use.

Summary

• Homebrew Cask provides the easiest macOS installation: brew install --cask codexbar
• Manual downloads work for both macOS UI and Linux CLI installations from GitHub Releases
• CLI helper installation requires running bin/install-codexbar-cli.sh after placing the app in /Applications
• Configuration persists in ~/.config/codexbar/config.json and syncs between UI and CLI components
• Both interfaces rely on the same core modules: Sources/CodexBar for the UI and Sources/CodexBarCLI for command-line operations

Frequently Asked Questions

Can I run the CodexBar UI on Linux?

No. The graphical menu-bar application requires macOS 14 or later. Linux users should download the CodexBarCLI tarball from GitHub Releases and use the command-line interface exclusively. The CLI provides full quota tracking capabilities via terminal commands.

How do I update CodexBar when installed via Homebrew?

Run brew upgrade --cask codexbar to update to the latest version. The Homebrew cask intentionally disables Sparkle automatic updates to prevent conflicts with Homebrew's package management system. The About panel in the app will display a message directing you to update via Homebrew rather than through the built-in updater.

Where does CodexBar store its configuration files?

CodexBar stores resolved configuration at ~/.config/codexbar/config.json for new installations. Legacy installs may still use ~/.codexbar/config.json. Both the UI app in Sources/CodexBar and the CLI in Sources/CodexBarCLI read from this location, ensuring settings remain consistent across interfaces.

Do I need to install the CLI separately if I use the Homebrew Cask?

Yes, if you want command-line access. The Homebrew Cask only installs the UI app bundle. To enable the codexbar command in your terminal, run the bundled installer script at bin/install-codexbar-cli.sh after the UI app is installed, or manually symlink /Applications/CodexBar.app/Contents/Helpers/CodexBarCLI to a directory in your PATH.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}