Does CodexBar Have a GUI or Is It CLI Only? Complete Interface Guide

CodexBar provides both a native macOS menu-bar GUI and a fully-featured command-line interface, allowing users to monitor AI coding usage through either a visual status bar or terminal commands.

CodexBar is a macOS 14+ utility designed to track usage and costs across multiple AI coding providers. Unlike tools that force you to choose between graphical and terminal interfaces, this open-source application delivers both experiences through a unified architecture. The primary interface runs as a lightweight menu-bar application, while a bundled codexbar executable offers headless automation capabilities and Linux support.

The Primary Interface: Native macOS Menu-Bar GUI

CodexBar functions primarily as a macOS menu-bar application that displays usage meters, reset timers, and status icons for various AI-coding providers. The application runs as an LSUIElement, meaning it operates without a Dock icon and persists only as a custom status item in the system menu bar.

Architecture and Implementation

The GUI implementation centers on Sources/CodexBar/StatusItemController.swift, which constructs the NSStatusBar item, handles menu interactions, and renders the icon. The application entry point in Sources/CodexBar/AppDelegate.swift initializes this controller alongside the Sparkle updater framework.

Key characteristics of the GUI implementation include:

• LSUIElement configuration: No Dock icon appears when the app launches
• NSStatusBar integration: Native macOS menu-bar rendering via StatusItemController
• Visual indicators: Real-time usage meters and provider status icons

According to docs/ui.md, the interface provides immediate visual feedback for API usage quotas and billing cycles without requiring terminal interaction.

The Command-Line Interface (CLI)

In addition to the graphical front-end, CodexBar ships with a bundled command-line interface accessible via the codexbar binary. The CLI sources reside under Sources/CodexBarCLI/, with argument parsing and command dispatch handled in Sources/CodexBarCLI/CLIEntry.swift.

CLI Commands and Usage

The CLI supports configuration management and cost queries that mirror the GUI's functionality:

# Launch the GUI (macOS)

open CodexBar.app                # builds the app with ./Scripts/package_app.sh

# Use the bundled CLI to list enabled providers

codexbar config providers        # → prints the provider list read from the config file

# Enable a provider from the command line

codexbar config enable --provider grok

# Run a cost‑usage scan from the terminal (works on macOS and Linux)

codexbar cost --provider openai   # prints OpenAI spend/credits summary

These commands execute the same core logic as the GUI buttons, reading from identical configuration stores and API endpoints.

Shared Architecture and Data Layer

Both interfaces consume the same underlying usage-store and provider logic, ensuring consistency whether you click a menu item or run a shell script. As documented in docs/architecture.md, the project separates concerns into distinct modules:

• GUI modules (CodexBar): AppKit-dependent code for macOS UI rendering
• CLI modules (CodexBarCLI): Argument parsing and terminal output formatting via CLIEntry.swift
• Shared core: Business logic for API querying and data persistence

This architecture enables Linux builds that leverage the CLI functionality without requiring macOS-specific UI frameworks.

Platform Availability and Launch Methods

Users can access CodexBar through multiple entry points depending on their platform and workflow:

# macOS: Launch the GUI (menu bar appears automatically, no Dock icon shown)

open CodexBar.app

# macOS/Linux: Execute CLI commands for automation

codexbar cost --provider openai
codexbar config enable --provider anthropic

The menu-bar GUI appears automatically after launching the .app bundle, while CLI commands execute immediately and exit without spawning the graphical interface. Linux distributions receive only the CLI components, as the GUI relies on macOS-specific NSStatusBar APIs.

Summary

• CodexBar offers both GUI and CLI interfaces, not just one or the other.
• The primary interface is a macOS menu-bar app (LSUIElement) implemented in Sources/CodexBar/StatusItemController.swift.
• The CLI provides headless automation via Sources/CodexBarCLI/CLIEntry.swift and works on both macOS and Linux.
• Both interfaces share identical usage-store and provider logic for consistent data across platforms.
• The GUI runs without a Dock icon, appearing only in the system status bar.

Frequently Asked Questions

Can I use CodexBar without the macOS GUI?

Yes. The codexbar CLI functions independently on macOS and Linux systems, allowing you to query costs and manage providers entirely from the terminal. The CLI shares the same configuration files and API logic as the graphical interface.

Does CodexBar show a Dock icon when running?

No. CodexBar runs as an LSUIElement (background-only application), so it displays only in the menu bar without appearing in the Dock or Command-Tab switcher. This behavior is implemented in Sources/CodexBar/AppDelegate.swift and confirmed in docs/ui.md.

How do I access the CLI if I only downloaded the GUI app?

The CLI binary is bundled inside the CodexBar application bundle. You can typically access it at CodexBar.app/Contents/MacOS/codexbar or install it to your system path using the provided installation scripts. The CLI is documented separately in docs/cli.md.

Is the Linux version of CodexBar CLI-only?

Yes. Linux builds provide only the command-line interface located in Sources/CodexBarCLI/, as the menu-bar GUI relies on macOS-specific AppKit frameworks (NSStatusBar) found in Sources/CodexBar/StatusItemController.swift.

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