[DOC]: CodexBar

Updated from 7/6/2026 📄 View raw md

📊 CodexBar (GNOME Shell Extension)

CodexBar is a GNOME Shell panel extension that displays real-time AI usage metrics and remaining quotas for various providers (Codex, Claude, Gemini, DeepSeek, etc.). It is based on the original codexbar command-line tool by @steipete.

🛠️ System Dependencies

For the extension to work correctly across all providers, you need to configure a few tools on your system.

1. CodexBar CLI (Required)

The official CLI binary queries the usage API for most providers.

Installation (Linux / macOS):
```
brew install steipete/tap/codexbar
```

2. Cookie Importer (Optional, for Codex/ChatGPT)

Extracts session cookies directly from your web browsers (Chrome, Brave, etc.) to perform an automatic login.

Installation:
```
pip install codexbar-cookie-importer
```

3. `lsof` Utility (Required for Antigravity)

The codexbar CLI relies on lsof on Linux to detect and communicate with the local Antigravity server ports.

Arch Linux Installation:
```
sudo pacman -S lsof
```
Debian / Ubuntu Installation:
```
sudo apt install lsof
```
Fedora Installation:
```
sudo dnf install lsof
```

4. SSL Redirect Shim (Required for Antigravity on Linux)

The local Antigravity server (agy) generates dynamic self-signed SSL certificates at startup. For the codexbar CLI to communicate securely with it without certificate errors, a compiled C shim is required to redirect the system's CA bundle.

Run the following script in your terminal to compile and install the shim persistently in your user directory:

curl -fsSL https://raw.githubusercontent.com/InledGroup/codexbar-gnome/main/install_shim.sh | bash

⚙️ Configuration & Usage

Open CodexBar Preferences from the panel drop-down menu or through the Extensions app.
Enable the AI providers you use.
For Antigravity, make sure the default command is configured and that the dependencies (lsof and the SSL shim) are installed. The extension will automatically handle injecting the required environment variables (LD_PRELOAD, CUSTOM_CA_BUNDLE, and ANTIGRAVITY_OAUTH_CREDENTIALS_JSON) during checks.

← Back to home