slug: codexbar-gnome
group: CodexBar

# 📊 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):**
  ```bash
  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:**
  ```bash
  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:**
  ```bash
  sudo pacman -S lsof
  ```
- **Debian / Ubuntu Installation:**
  ```bash
  sudo apt install lsof
  ```
- **Fedora Installation:**
  ```bash
  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:
```bash
curl -fsSL https://raw.githubusercontent.com/InledGroup/codexbar-gnome/main/install_shim.sh | bash
```

---

## ⚙️ Configuration & Usage

1. Open **CodexBar Preferences** from the panel drop-down menu or through the *Extensions* app.
2. Enable the AI providers you use.
3. 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.