CodexBar GNOME Extension

Show AI provider usage (Codex, Claude, Gemini) from the CodexBar CLI in the GNOME top panel.

RC-1.1 compatibility

• codexbar v0.1.1-rc.1
• [email protected] v0.1.1-rc.1

This RC pair is validated together. The extension still relies on the RC-1 status --json contract (unchanged) and now additionally consumes runtime provider metadata from codexbar providers --json.

RC-1.1 scope is Dynamic Provider Metadata only:

• status --json is unchanged from RC-1.
• config dump / config set-provider behavior is unchanged.
• providers --json is read-only, versioned (schemaVersion: 1), and used to overlay known providers in runtime UI.
• providerRegistry.js remains the fallback when metadata is missing/invalid or when the CLI is older than RC-1.1.

RC-1.1.1 (Extension-only) adds Usage/Quota UI polish with no CLI contract changes. It standardizes popup/panel state rendering and readable error text.

Validation note:

• node --check passed.
• GNOME cliBridge fixture tests passed.
• GNOME provider metadata fixture tests passed.
• dev-check passed.
• Swift focused filter tests built successfully, but Linux test discovery reported 0 matching tests in this environment.
• Full make check passed outside sandbox.

The extension is a thin frontend — all provider auth, parsing, and status collection happen inside the codexbar CLI binary. The extension only executes the CLI, parses its JSON output, and renders the result.

Requirements

• GNOME Shell 47 or later (tested on 47, 48, 50)
• codexbar CLI available on PATH (or set an absolute path in Settings)
• At least one AI provider authenticated through the CLI

Install from ZIP (recommended)

gnome-extensions install --force [email protected]
gnome-extensions enable [email protected]

On Wayland, log out and back in after the first install if the icon does not appear.

Verify:

gnome-extensions info [email protected]

Install from source

./[email protected]/install.sh

The script copies extension files, compiles the GSettings schema, and re-enables the extension. Re-run it to update.

Install the CodexBar CLI

Build from source (requires Swift toolchain):

swift build -c release --product CodexBarCLI
mkdir -p ~/.local/bin
ln -sf "$(pwd)/.build/release/CodexBarCLI" ~/.local/bin/codexbar

Or install a pre-built release tarball that provides codexbar for Linux.

Verify the CLI is reachable from a login shell:

command -v codexbar
codexbar status --json --provider codex

Provider authentication and policy

Authentication happens entirely through the CLI — never through the extension. For RC-1.1, provider policy is loaded in this order:

1. Runtime metadata from codexbar providers --json (known providers only)
2. Static fallback from providerRegistry.js

Unknown providers from runtime metadata are intentionally ignored in UI for RC-1.1.

RC-1.1.1 UI state policy

Badge precedence is deterministic:

1. disabled
2. auth_required
3. quota_exceeded
4. error
5. degraded
6. stale
7. ok
8. unknown

If a provider is stale and also has a stronger state (for example auth_required or error), the stronger state is shown as the primary badge and stale is shown as a secondary hint.

Provider and refresh errors are shown with readable user-facing messages in primary UI surfaces; raw CLI error text is not shown in popup primary content.

| Provider | Source options | Auth actions | API key input | |----------|----------------|--------------|---------------| | Codex | oauth, cli | Open OAuth, Run Login (codex login) | Disabled | | Claude | oauth, cli | Open OAuth, Run Login (claude login) | Disabled | | Gemini | api | Open OAuth, Run Login (gemini) | Disabled | | Development | mock | None | Disabled |

After authenticating each provider, verify with:

codexbar status --json --provider codex
codexbar status --json --provider claude
codexbar status --json --provider gemini --source api

Settings

Open the preferences window:

gnome-extensions prefs [email protected]

Key settings:

| Setting | Default | Description | |---------|---------|-------------| | Enabled providers | codex, claude, gemini | Which providers to poll | | Command path | codexbar | Absolute path if GNOME Shell cannot find the CLI | | Refresh interval | 300 s | How often to re-poll the CLI | | Per-provider source | provider defaults | Source is configured per provider in the corresponding provider card | | Connection/Auth | provider defaults | Use Open OAuth / Run Login buttons in each provider card |

Compatibility matrix

| CLI | Extension | Result | |-----|-----------|--------| | v0.1.1-rc.1 | v0.1.1-rc.1 | Full RC-1.1 path (status + runtime metadata) | | v0.1.0-rc.1 | v0.1.1-rc.1 | Works with fallback (providerRegistry.js) | | older than v0.1.0-rc.1 | v0.1.1-rc.1 | Not supported |

Migration from RC-1

• Keep using the same status --json and config commands.
• Upgrade CLI first, then extension, to enable runtime provider metadata.
• No new auth flow is required; existing Open OAuth / Run Login behavior is unchanged.

Update

From ZIP:

gnome-extensions install --force [email protected]

From source:

git pull
./[email protected]/install.sh

Settings are preserved across updates.

Uninstall

./[email protected]/install.sh --uninstall

Or:

gnome-extensions uninstall [email protected]

Troubleshooting

AI! appears in the panel

AI! means the CLI command failed to start or returned invalid JSON — a global error. Check that codexbar is on the PATH visible to GNOME Shell:

# Confirm codexbar is found
command -v codexbar

# Set an absolute path in Settings if GNOME Shell cannot find it
gnome-extensions prefs [email protected]
# → Backend → Command path → /home/<you>/.local/bin/codexbar

Or set it from the command line:

GSETTINGS_SCHEMA_DIR="$HOME/.local/share/gnome-shell/extensions/[email protected]/schemas" \
  gsettings set org.gnome.shell.extensions.codexbar command-path "$HOME/.local/bin/codexbar"

A single provider shows an error

Provider-specific errors (e.g. "Claude CLI not found", "Not logged in") appear only in that provider's row and never change the panel to AI!. Check the provider row in the popup menu or the Provider Status section in the preferences window for the exact error message.

Extension does not appear after install

On Wayland, log out and back in. On X11, restart GNOME Shell with Alt+F2 → r → Enter.

Reading GNOME Shell logs

journalctl --user -f -o cat /usr/bin/gnome-shell

Or open Looking Glass: Alt+F2 → lg → Enter.

Build a release ZIP

./[email protected]/package.sh
# Produces: [email protected]

The script runs dev-check.sh, recompiles the schema, and validates the ZIP structure before reporting success.

Development checks

# Full static check suite (syntax, schema, secrets, fixture test)
./[email protected]/dev-check.sh

# Fixture test only (no live GNOME Shell needed)
gjs -m [email protected]/test/cliBridge-fixture-test.js