CodexBar

https://github.com/steipete/codexbar
Admin
CodexBar is a macOS menu bar app that monitors token usage limits and reset windows for multiple AI...
Tokens:261,974
Snippets:2,190
Trust Score:10
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and start CodexBar for Omarchy

Source: https://github.com/steipete/codexbar/blob/main/Integrations/Omarchy/README.md

Build the Linux desktop app first, then run these commands from the repository root. The installer migrates old widget settings, backs up shell.json, and adds a launcher and autostart entry. The CLI resource bundle must stay beside its binary.

```sh
python3 Integrations/Linux/install.py --omarchy --cli /absolute/path/to/codexbar
~/.local/bin/codexbar-linux --background
omarchy restart shell
```

--------------------------------

### Minimal provider example (Swift)

Source: https://github.com/steipete/codexbar/blob/main/docs/provider.md

Copy-paste template for a new provider. Defines an ExampleProviderDescriptor with metadata, branding, token cost, fetch plan, and CLI config, plus an ExampleFetchStrategy that returns a zero-usage snapshot. Use as a starting point for implementing a new provider.

```swift
import Foundation

public enum ExampleProviderDescriptor {
    public static let descriptor: ProviderDescriptor = Self.makeDescriptor()

    static func makeDescriptor() -> ProviderDescriptor {
        ProviderDescriptor(
            id: .example,
            metadata: ProviderMetadata(
                id: .example,
                displayName: "Example",
                sessionLabel: "Session",
                weeklyLabel: "Weekly",
                opusLabel: nil,
                supportsOpus: false,
                supportsCredits: false,
                creditsHint: "",
                toggleTitle: "Show Example usage",
                cliName: "example",
                defaultEnabled: false,
                isPrimaryProvider: false,
                usesAccountFallback: false,
                dashboardURL: nil,
                statusPageURL: nil),
            branding: ProviderBranding(
                iconStyle: .init(provider: .example),
                iconResourceName: "ProviderIcon-example",
                color: ProviderColor(red: 0.2, green: 0.6, blue: 0.8),
                confettiPalette: [
                    ProviderColor(hex: 0x3399CC),
                    ProviderColor(hex: 0x66C2FF),
                ]),
            tokenCost: ProviderTokenCostConfig(
                supportsTokenCost: false,
                noDataMessage: { "Example cost summary is not supported." }),
            fetchPlan: ProviderFetchPlan(
                sourceModes: [.auto, .cli],
                pipeline: ProviderFetchPipeline(resolveStrategies: { _ in [ExampleFetchStrategy()] })),
            cli: ProviderCLIConfig(
                name: "example",
                versionDetector: nil))
    }
}

struct ExampleFetchStrategy: ProviderFetchStrategy {
    let id: String = "example.cli"
    let kind: ProviderFetchKind = .cli

    func isAvailable(_: ProviderFetchContext) async -> Bool { true }

    func fetch(_: ProviderFetchContext) async throws -> ProviderFetchResult {
        let usage = UsageSnapshot(
            primary: .init(usedPercent: 0, windowMinutes: nil, resetsAt: nil, resetDescription: nil),
            secondary: nil,
            updatedAt: Date(),
            identity: nil)
        return self.makeResult(usage: usage, sourceLabel: "cli")
    }

    func shouldFallback(on _: Error, context _: ProviderFetchContext) -> Bool { false }
}
```

--------------------------------

### Build and install CodexBar from source

Source: https://github.com/steipete/codexbar/blob/main/Integrations/Linux/README.md

Commands to build the project using qmake6 and make, followed by the installation script and initial settings configuration.

```sh
mkdir -p .local/linux-build
cd .local/linux-build
qmake6 ../../Integrations/Linux/codexbar-linux.pro
make -j4
cd ../..
python3 Integrations/Linux/install.py --cli /absolute/path/to/codexbar
~/.local/bin/codexbar-linux --settings
```

--------------------------------

### Install Linux desktop archive

Source: https://github.com/steipete/codexbar/blob/main/README.md

Verify, extract, and install the Linux desktop archive and CLI integration.

```bash
archive='CodexBarDesktop-v<version>-linux-x86_64.tar.gz'
sha256sum -c "$archive.sha256"
tar -xzf "$archive"
cd "${archive%.tar.gz}"
python3 Integrations/Linux/install.py --cli /absolute/path/to/codexbar --omarchy
~/.local/bin/codexbar-linux --settings
```

--------------------------------

### Install Linux runtime dependencies

Source: https://github.com/steipete/codexbar/blob/main/README.md

Install required system packages for the Qt 6 desktop app on Arch or Omarchy.

```bash
sudo pacman -S --needed python qt6-base qt6-declarative qt6-svg qt6-wayland
```

--------------------------------

### Install mimo-usage.py to PATH

Source: https://github.com/steipete/codexbar/blob/main/docs/mimo.md

Symlinks the shipped Scripts/mimo-usage.py into ~/.local/bin and makes it executable. Run once to install the mimo-usage command used by the local fallback.

```bash
ln -sf "$(pwd)/Scripts/mimo-usage.py" ~/.local/bin/mimo-usage
chmod +x ~/.local/bin/mimo-usage
```

--------------------------------

### Install CodexBar CLI via Homebrew

Source: https://github.com/steipete/codexbar/blob/main/README.md

Install the CLI tool using the Homebrew tap.

```bash
brew install steipete/tap/codexbar
```

--------------------------------

### Install CodexBar CLI via repo script

Source: https://github.com/steipete/codexbar/blob/main/docs/cli.md

Run the installer script from the repo after installing CodexBar.app in /Applications. It symlinks CodexBarCLI to /usr/local/bin/codexbar and /opt/homebrew/bin/codexbar, requires macOS administrator approval, and errors if the helper is missing.

```bash
./bin/install-codexbar-cli.sh
```

--------------------------------

### Install CodexBar CLI

Source: https://github.com/steipete/codexbar/blob/main/README.md

Installs the CodexBar CLI tool after the application has been installed in /Applications.

```bash
# after installing CodexBar.app in /Applications
./bin/install-codexbar-cli.sh
```

--------------------------------

### Install and configure CodexBar on Linux

Source: https://github.com/steipete/codexbar/blob/main/Integrations/Linux/README.md

Commands to verify the downloaded archive, extract the files, run the installation script, and launch the settings window.

```sh
# Download the archive and its checksum into the same directory.
# Replace <version> below with the downloaded version (use aarch64 for ARM64):
archive='CodexBarDesktop-v<version>-linux-x86_64.tar.gz'
sha256sum -c "$archive.sha256"
tar -xzf "$archive"
cd "${archive%.tar.gz}"
python3 Integrations/Linux/install.py --cli /absolute/path/to/codexbar --omarchy
~/.local/bin/codexbar-linux --settings
```

--------------------------------

### Install CodexBar from archive

Source: https://github.com/steipete/codexbar/blob/main/Integrations/Linux/README.md

Command to install the CodexBar Linux CLI from an extracted archive with the Omarchy adapter enabled.

```sh
# Inside an extracted CodexBarDesktop archive:
python3 Integrations/Linux/install.py --cli /absolute/path/to/codexbar --omarchy
```

--------------------------------

### Set API keys for multiple providers

Source: https://github.com/steipete/codexbar/blob/main/docs/cli-configuration.md

Useful examples for setting API keys for multiple providers. Each command reads the key from an environment variable and pipes it to set-api-key via --stdin.

```bash
printf '%s' "$OPENAI_ADMIN_KEY" | codexbar config set-api-key --provider openai --stdin
printf '%s' "$ANTHROPIC_ADMIN_KEY" | codexbar config set-api-key --provider claude --stdin
printf '%s' "$DEEPGRAM_API_KEY" | codexbar config set-api-key --provider deepgram --stdin
printf '%s' "$GROQ_API_KEY" | codexbar config set-api-key --provider groq --stdin
printf '%s' "$LLM_PROXY_API_KEY" | codexbar config set-api-key --provider llmproxy --stdin
printf '%s' "$Z_AI_API_KEY" | codexbar config set-api-key --provider zai --stdin
printf '%s' "$XAI_MANAGEMENT_API_KEY" | codexbar config set-api-key --provider xai --stdin
```

--------------------------------

### Sample text output from codexbar

Source: https://github.com/steipete/codexbar/blob/main/docs/cli.md

Example of the default text output showing usage, pace, and credits for multiple providers.

```text
== Codex 0.6.0 (codex-cli) ==
Session: 72% left [========----]
Pace: 12% in deficit | Expected 16% used | Projected empty in 2h 30m
Resets today at 2:15 PM
Weekly: 41% left [====--------]
Pace: 6% in reserve | Expected 47% used | Lasts until reset
Resets Fri at 9:00 AM
Credits: 112.4 left

== Claude Code 2.0.58 (web) ==
Session: 88% left [==========--]
Pace: On pace | Expected 13% used | Lasts until reset
Resets tomorrow at 1:00 AM
Weekly: 63% left [=======-----]
Pace: On pace | Expected 37% used | Runs out in 4d
Resets Sat at 6:00 AM
Sonnet: 95% left [===========-]
Account: user@example.com
Plan: Pro

== Kilo (cli) ==
Credits: 60% left [=======-----]
40/100 credits
Plan: Kilo Pass Pro
Activity: Auto top-up: visa
Note: Using CLI fallback
```

--------------------------------

### Start Quotio Analysis

Source: https://github.com/steipete/codexbar/blob/main/docs/FORK_SETUP.md

Command to initiate the Quotio analysis process, followed by editing the analysis documentation.

```bash
./Scripts/analyze_quotio.sh
# Then edit docs/QUOTIO_ANALYSIS.md
```

--------------------------------

### codexbar CLI usage examples

Source: https://github.com/steipete/codexbar/blob/main/docs/cli.md

Shows common codexbar commands for querying usage, costs, and configuration. Includes flags for provider selection, output format, and environment variables for authentication.

```bash
codexbar                          # text, respects app toggles
codexbar --provider claude        # force Claude
codexbar --provider all           # query all registered providers
codexbar --format json --pretty   # machine output
codexbar --format json --provider both
codexbar cost                     # cost usage (default 30-day window + today)
codexbar cost --days 90           # choose a 1...365 day cost window
codexbar cost --provider codex --group-by project
codexbar cost --provider codex --group-by session
codexbar cost --provider claude --format json --pretty
codexbar guard --provider codex --min-remaining 20 --window weekly --json
codexbar cost --provider cursor   # Cursor dashboard cost (API-rate + Cursor-metered)
codexbar dashboard | jq '.providers[] | {id, windows, error}'
codexbar serve --port 8080        # localhost HTTP JSON server
codexbar serve --request-timeout 0 # disable serve request deadlines
CODEXBAR_DASHBOARD_TOKEN=YOUR_TOKEN codexbar serve # token-gated dashboard snapshot
CODEXBAR_DASHBOARD_TOKEN=... codexbar serve --host 0.0.0.0 --allow-plain-http # LAN, cleartext accepted
COPILOT_API_TOKEN=... codexbar --provider copilot --format json --pretty
codexbar --status                 # include status page indicator/description
codexbar --provider codex --source oauth --format json --pretty
codexbar --provider codex --source web --format json --pretty
codexbar --provider codex --all-accounts --format json --pretty
codexbar --provider claude --account steipete@gmail.com
codexbar --provider claude --all-accounts --format json --pretty
codexbar --json-only --format json --pretty
codexbar --provider gemini --source api --format json --pretty
KILO_API_KEY=... codexbar --provider kilo --source api --format json --pretty
MOONSHOT_API_KEY=... codexbar --provider moonshot --source api --format json --pretty
codexbar config validate --format json --pretty
codexbar config dump --pretty
printf '%s' "$OPENAI_ADMIN_KEY" | codexbar config set-api-key --provider openai --stdin
codexbar config enable --provider grok
codexbar cache clear --cookies
codexbar cache clear --cookies --provider claude
codexbar cache clear --all --format json --pretty
codexbar cookie refresh --provider opencodego --allow-keychain-prompt
```

--------------------------------

### Run CodexBar with Poe provider

Source: https://github.com/steipete/codexbar/blob/main/docs/poe.md

Starts CodexBar using the Poe provider.

```bash
codexbar --provider poe
```

--------------------------------

### Install CodexBar on macOS via Homebrew

Source: https://github.com/steipete/codexbar/blob/main/README.md

Use Homebrew to install the CodexBar macOS application.

```bash
brew install --cask codexbar
```

--------------------------------

### Custom pricing overlay JSON example

Source: https://github.com/steipete/codexbar/blob/main/docs/model-pricing.md

Example custom-pricing.json overlay. Keys are case-insensitive and may be bare model IDs or provider/model. Bare keys win over provider-qualified rows. Values are USD per million tokens; 0 means free, missing fields stay unknown, and negative/non-finite numbers are ignored.

```json
{
  "gpt-5.4": {
    "input": 1.25,
    "output": 10,
    "cacheRead": 0.125,
    "cacheWrite": 1.25
  },
  "openai/gpt-5.4-mini": {
    "input": 0,
    "output": 0
  }
}
```

--------------------------------

### Sample JSON output from codexbar

Source: https://github.com/steipete/codexbar/blob/main/docs/cli.md

Example of the JSON output with --format json --pretty, showing provider usage, pace, credits, and dashboard data.

```json
{
  "provider": "codex",
  "version": "0.6.0",
  "source": "openai-web",
  "status": { "indicator": "none", "description": "Operational", "updatedAt": "2025-12-04T17:55:00Z", "url": "https://status.openai.com/" },
  "usage": {
    "primary": { "usedPercent": 28, "windowMinutes": 300, "resetsAt": "2025-12-04T19:15:00Z" },
    "secondary": { "usedPercent": 59, "windowMinutes": 10080, "resetsAt": "2025-12-05T17:00:00Z" },
    "tertiary": null,
    "updatedAt": "2025-12-04T18:10:22Z",
    "identity": {
      "providerID": "codex",
      "accountEmail": "user@example.com",
      "accountOrganization": null,
      "loginMethod": "plus"
    },
    "accountEmail": "user@example.com",
    "accountOrganization": null,
    "loginMethod": "plus"
  },
  "pace": {
    "primary": { "stage": "ahead", "deltaPercent": 12, "expectedUsedPercent": 16, "willLastToReset": false, "etaSeconds": 9000, "summary": "12% in deficit | Expected 16% used | Projected empty in 2h 30m" },
    "secondary": { "stage": "slightlyBehind", "deltaPercent": -6, "expectedUsedPercent": 47, "willLastToReset": true, "summary": "6% in reserve | Expected 47% used | Lasts until reset" }
  },
  "credits": { "remaining": 112.4, "updatedAt": "2025-12-04T18:10:21Z" },
  "antigravityPlanInfo": null,
  "openaiDashboard": {
    "signedInEmail": "user@example.com",
    "codeReviewRemainingPercent": 100,
    "creditEvents": [
      { "id": "00000000-0000-0000-0000-000000000000", "date": "2025-12-04T00:00:00Z", "service": "CLI", "creditsUsed": 123.45 }
    ],
    "dailyBreakdown": [
      {
        "day": "2025-12-04",
        "services": [{ "service": "CLI", "creditsUsed": 123.45 }],
        "totalCreditsUsed": 123.45
      }
    ],
    "updatedAt": "2025-12-04T18:10:21Z"
  }
}
```

--------------------------------

### Install CodexBar CLI via AUR

Source: https://github.com/steipete/codexbar/blob/main/README.md

Install the CLI tool using the Arch Linux AUR package.

```bash
yay -S codexbar-cli
```

--------------------------------

### Check for duplicate widget installations

Source: https://github.com/steipete/codexbar/blob/main/docs/widgets.md

Identifies multiple paths for the same widget ID, which may indicate old installs or version conflicts.

```bash
pluginkit -m -D -p com.apple.widgetkit-extension -i "$WIDGET_ID" -vv
```

--------------------------------

### Minimal provider plugin definition

Source: https://github.com/steipete/codexbar/blob/main/docs/plugins.md

A basic example of a provider plugin using defineProvider, including manifest metadata, authentication configuration, settings schema, and the fetchUsage implementation.

```js
defineProvider({
  id: "acme-usage",
  name: "Acme Usage",
  icon: { monogram: "AC", tint: "#336699" },
  endpoints: ["https://api.example.com"],
  auth: { type: "bearer", secret: "API_KEY" },
  settings: [
    { key: "API_KEY", title: "API key", subtitle: "Create one in Acme settings.", type: "secure" },
  ],
  async fetchUsage(ctx) {
    const response = await ctx.http.getJSON("https://api.example.com/v1/usage");
    return {
      primary: {
        usedPercent: response.json.used_percent,
        resetsAt: response.json.resets_at,
        windowMinutes: 300,
      },
      details: [{
        title: "Usage",
        rows: [{ label: "Requests", value: String(response.json.requests) }],
      }],
    };
  },
});
```

--------------------------------

### Extract and run CodexBar CLI from release tarball

Source: https://github.com/steipete/codexbar/blob/main/docs/cli.md

Download a release tarball, extract it, and run the CLI. The example uses the macOS x86_64 tarball and shows checking the version and fetching usage in pretty JSON format.

```bash
tar -xzf CodexBarCLI-v0.17.0-macos-x86_64.tar.gz
./codexbar --version
./codexbar usage --format json --pretty
```

--------------------------------

### Team configuration JSON structure

Source: https://github.com/steipete/codexbar/blob/main/docs/zai.md

Example of the JSON structure required for team accounts in the codexbar configuration file.

```json
{
  "id": "zai",
  "enabled": true,
  "region": "bigmodel-cn",
  "tokenAccounts": {
    "version": 1,
    "activeIndex": 0,
    "accounts": [
      {
        "id": "00000000-0000-0000-0000-000000000001",
        "label": "Team",
        "token": "<z.ai API key>",
        "addedAt": 0,
        "lastUsed": null,
        "usageScope": "team",
        "organizationId": "org_...",
        "workspaceID": "proj_..."
      }
    ]
  }
}
```

--------------------------------

### Quotio-inspired commit message example

Source: https://github.com/steipete/codexbar/blob/main/docs/UPSTREAM_STRATEGY.md

Use for commits that attribute inspiration to an external project while noting independent implementation. The message includes a link to the referenced project and clarifies the implementation approach.

```text
feat: implement session persistence inspired by quotio

Adds automatic session restoration on app restart.

Inspired by quotio's approach:
https://github.com/nguyenphutrong/quotio/blob/main/...

Implemented independently using CodexBar patterns.
```

--------------------------------

### Configure advanced profile-home accounts in ~/.codexbar/config.json

Source: https://github.com/steipete/codexbar/blob/main/docs/codex.md

Add existing Codex homes to the CodexBar configuration file using the providers[].codexProfileHomePaths key. Each path must be absolute or start with ~/ and point to a Codex home containing auth.json. CodexBar reads identity from these homes and scopes remote fetches with CODEX_HOME.

```json
{
  "id": "codex",
  "codexProfileHomePaths": [
    "~/.codex-work",
    "~/.codex-personal"
  ]
}
```

--------------------------------

### Fork-family graph tree example

Source: https://github.com/steipete/codexbar/blob/main/docs/issue-2037-fork-family-provenance-spec.md

Shows a simple fork-family graph with a root session and two child branches, illustrating the hierarchy of sessions that form one reconciliation unit.

```text
root session
├── child A
│   └── grandchild
└── child B
```

--------------------------------

### Add fetchOrganizations and helper methods

Source: https://github.com/steipete/codexbar/blob/main/docs/superpowers/plans/2026-05-11-kilo-organization-selection.md

Append this implementation to `Sources/CodexBarCore/Providers/Kilo/KiloUsageFetcher.swift` inside the `KiloUsageFetcher` struct. It fetches organizations via a tRPC GET request to `user.getOrganizations`, falls back to `fetchOrganizationsRESTFallback` on HTTP 404, and throws `KiloUsageError.missingCredentials` for empty API keys.

```swift
    public static func fetchOrganizations(
        apiKey: String,
        environment: [String: String] = ProcessInfo.processInfo.environment) async throws -> [KiloOrganization]
    {
        guard !apiKey.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
            throw KiloUsageError.missingCredentials
        }

        let baseURL = KiloSettingsReader.apiURL(environment: environment)
        let trpcRequest = try self.makeOrgListTRPCRequest(baseURL: baseURL, apiKey: apiKey)

        do {
            let (data, response) = try await URLSession.shared.data(for: trpcRequest)
            guard let httpResponse = response as? HTTPURLResponse else {
                throw KiloUsageError.networkError("Invalid response")
            }
            if httpResponse.statusCode == 404 {
                return try await self.fetchOrganizationsRESTFallback(apiKey: apiKey)
            }
            if let mapped = self.statusError(for: httpResponse.statusCode) {
                throw mapped
            }
            return try self.parseOrganizations(data: data)
        } catch let error as KiloUsageError {
            throw error
        } catch {
            throw KiloUsageError.networkError(error.localizedDescription)
        }
    }

    static func _parseOrganizationsForTesting(_ data: Data) throws -> [KiloOrganization] {
        try self.parseOrganizations(data: data)
    }

    private static func makeOrgListTRPCRequest(
        baseURL: URL,
        apiKey: String) throws -> URLRequest
    {
        let endpoint = baseURL.appendingPathComponent("user.getOrganizations")
        let inputData = try JSONSerialization.data(
            withJSONObject: ["0": ["json": NSNull()]] as [String: Any])
        guard let inputString = String(data: inputData, encoding: .utf8),
              var components = URLComponents(url: endpoint, resolvingAgainstBaseURL: false) else {
            throw KiloUsageError.parseFailed("Invalid org list endpoint")
        }
        components.queryItems = [
            URLQueryItem(name: "batch", value: "1"),
            URLQueryItem(name: "input", value: inputString),
        ]
        guard let url = components.url else {
            throw KiloUsageError.parseFailed("Invalid org list endpoint")
        }
        var request = URLRequest(url: url)
        request.httpMethod = "GET"
        request.timeoutInterval = 15
        request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")
        request.setValue("application/json", forHTTPHeaderField: "Accept")
        return request
    }
```

--------------------------------

### Generate and Configure Dashboard Token

Source: https://github.com/steipete/codexbar/blob/main/docs/dashboard-api.md

Commands to generate a secure token and start the server using either an environment variable or a command-line flag. The environment variable is preferred to prevent token leakage via process lists.

```bash
# Generate a strong token
openssl rand -hex 32

# Preferred: environment variable (argv leaks via `ps`)
CODEXBAR_DASHBOARD_TOKEN=YOUR_TOKEN codexbar serve

# Also accepted, but visible in the process list
codexbar serve --dashboard-token YOUR_TOKEN
```

--------------------------------

### Kimi Code API usage response

Source: https://github.com/steipete/codexbar/blob/main/docs/kimi.md

Example JSON response from the Kimi Code API endpoint `GET https://api.kimi.com/coding/v1/usages`. Shows usage limits, used, remaining, and reset time, plus a nested limits array with a 300-minute window.

```json
{
  "usage": {
    "limit": "2048",
    "used": "214",
    "remaining": "1834",
    "resetTime": "2026-01-09T15:23:13.716839300Z"
  },
  "limits": [{
    "window": {"duration": 300, "timeUnit": "TIME_UNIT_MINUTE"},
    "detail": {
      "limit": "200",
      "used": "139",
      "remaining": "61",
      "resetTime": "2026-01-06T13:33:02.717479433Z"
    }
  }]
}
```

--------------------------------

### Manual Rebuild and Relaunch

Source: https://github.com/steipete/codexbar/blob/main/docs/DEVELOPMENT_SETUP.md

Packages the app, kills running instances, and launches the app without running tests.

```bash
./Scripts/package_app.sh
pkill -x CodexBar || pkill -f CodexBar.app || true
open -n CodexBar.app
```

--------------------------------

### x.ai/billing result shape

Source: https://github.com/steipete/codexbar/blob/main/docs/grok.md

Example response from the x.ai/billing RPC method. All monetary values are in cents. Shows billing cycle, monthly limit, on-demand cap, and usage totals.

```json
{
  "billingCycle": {
    "billingPeriodStart": "2026-05-01T00:00:00Z",
    "billingPeriodEnd": "2026-06-01T00:00:00Z"
  },
  "monthlyLimit": { "val": 99900 },
  "onDemandCap": { "val": 0 },
  "on_demand_enabled": false,
  "disabledByConfig": false,
  "usage": {
    "includedUsed": { "val": 12345 },
    "onDemandUsed": { "val": 0 },
    "totalUsed": { "val": 12345 }
  }
}
```

--------------------------------

### Declarative details example

Source: https://github.com/steipete/codexbar/blob/main/docs/plugin-prototype.md

Shows a snapshot with a primary usage percentage and a details array containing a section with rows and a bar chart. The bridge rejects more than 8 sections, 24 rows per section, or 120 points per chart, and enforces string length and type constraints.

```javascript
return {
  primary: { usedPercent: 25 },
  details: [{
    title: "Usage summary",
    rows: [
      { label: "Requests", value: "1,240", secondaryValue: "Last 30 days" },
      { label: "Top model", value: "gpt-5" },
    ],
    chart: {
      kind: "bars", // bars | line
      title: "Daily spend",
      unit: "USD",
      points: [
        { label: "2026-08-01", value: 4.25 },
        { label: "2026-08-02", value: 6.50 },
      ],
    },
  }],
};
```

--------------------------------

### Selective cherry-pick with commit review

Source: https://github.com/steipete/codexbar/blob/main/docs/FORK_SETUP.md

Shows how to review upstream commits and selectively cherry-pick the ones to sync, skipping the Augment removal commit. The example output marks commits with ✅ SYNC or ❌ SKIP.

```bash
# Review upstream commits
git log --oneline main..upstream/main

# Example output:
# 001019c style: fix swiftformat violations ✅ SYNC
# e4f1e4c feat(vertex): add token cost tracking ✅ SYNC
# 202efde fix(vertex): disable double-counting ✅ SYNC
# 0c2f888 docs: add Vertex AI documentation ✅ SYNC
# 3c4ca30 feat(vertexai): token cost tracking ✅ SYNC
# abc123d refactor: remove Augment provider ❌ SKIP

# Cherry-pick the good ones
git cherry-pick 001019c
git cherry-pick e4f1e4c
git cherry-pick 202efde
git cherry-pick 0c2f888
git cherry-pick 3c4ca30
# Skip abc123d (Augment removal)
```

--------------------------------

### Verify Homebrew cask install

Source: https://github.com/steipete/codexbar/blob/main/docs/releasing-homebrew.md

Verifies the Homebrew cask installation after updating the tap. Uninstalls any existing cask, untaps and re-taps the repository, installs the cask, and opens the app.

```sh
brew uninstall --cask codexbar || true
brew untap steipete/tap || true
brew tap steipete/tap
brew install --cask steipete/tap/codexbar
open -a CodexBar
```

--------------------------------

### Set PATH to Homebrew Python for make check and make test

Source: https://github.com/steipete/codexbar/blob/main/docs/DEVELOPMENT.md

Selects the generic commands of an installed Homebrew Python (python@3.14) so that make check and make test can run. Use these commands when the default python3 lacks os.waitid with WNOWAIT.

```bash
PATH="$(brew --prefix python@3.14)/libexec/bin:$PATH" make check
```

```bash
PATH="$(brew --prefix python@3.14)/libexec/bin:$PATH" make test
```

--------------------------------

### Build and verify with swift build

Source: https://github.com/steipete/codexbar/blob/main/docs/superpowers/plans/2026-05-11-kilo-organization-selection.md

Builds the project and shows the last 10 lines of output. Expected to succeed; if type mismatches arise, follow them and align signatures.

```bash
swift build 2>&1 | tail -10
```

--------------------------------

### Build CodexBar from source

Source: https://github.com/steipete/codexbar/blob/main/README.md

Builds the CodexBar.app in-place with ad-hoc signing and opens the application.

```bash
./Scripts/package_app.sh        # builds CodexBar.app in-place with ad-hoc signing
open CodexBar.app
```

--------------------------------

### Verify Swift toolchain and tests

Source: https://github.com/steipete/codexbar/blob/main/docs/superpowers/plans/2026-05-11-kilo-organization-selection.md

Build the project and run existing KiloUsageFetcher tests to ensure a stable baseline.

```bash
swift build 2>&1 | tail -5
swift test --filter KiloUsageFetcherTests 2>&1 | tail -10
```

--------------------------------

### CodexBar Linux CLI commands

Source: https://github.com/steipete/codexbar/blob/main/Integrations/Linux/README.md

CLI commands for the CodexBar Linux adapter. Snapshot, refresh, configure, autostart, and quit require an existing process; UI commands start one when needed. IPC clients load no GUI plugin. The private, same-user local socket lives at $XDG_RUNTIME_DIR/codexbar-linux/desktop.sock; requests and replies are newline-terminated JSON.

```sh
codexbar-linux --background
codexbar-linux --usage
codexbar-linux --settings
codexbar-linux --spending
codexbar-linux --refresh
codexbar-linux --snapshot
codexbar-linux --configure '{"provider":"both","refreshSeconds":300}'
codexbar-linux --autostart status # also enable or disable
codexbar-linux --quit
```

--------------------------------

### Learning from quotio with attribution

Source: https://github.com/steipete/codexbar/blob/main/docs/UPSTREAM_STRATEGY.md

Learn from the quotio project: analyze it, review its multi-account implementation, document patterns, then implement independently. Commit with attribution referencing the inspiration and noting independent implementation.

```bash
# Analyze quotio
./Scripts/analyze_quotio.sh

# Review their multi-account implementation
git show quotio/main:path/to/AccountManager.swift

# Document patterns in docs/QUOTIO_ANALYSIS.md
# Then implement independently in your fork

# Commit with attribution
git commit -m "feat: implement multi-account management

Inspired by quotio's account switching pattern:
https://github.com/nguyenphutrong/quotio/...

Implemented independently using CodexBar's architecture."
```

--------------------------------

### Repository Overview Commands

Source: https://github.com/steipete/codexbar/blob/main/docs/QUOTIO_ANALYSIS.md

Commands to fetch the Quotio repository, list relevant files, and check recent activity.

```bash
# Fetch latest quotio
./Scripts/analyze_quotio.sh

# Review file structure
git ls-tree -r --name-only quotio/main | grep -E '\.(swift|md)$'

# Check recent activity
git log --oneline --graph quotio/main --since="30 days ago"
```

--------------------------------

### GET request to tRPC getCustomerData

Source: https://github.com/steipete/codexbar/blob/main/docs/t3chat.md

The single GET request used by CodexBar to fetch customer data from the T3 Chat API.

```text
GET https://t3.chat/api/trpc/getCustomerData?batch=1&input=...
```

--------------------------------

### Build to verify schema compiles

Source: https://github.com/steipete/codexbar/blob/main/docs/superpowers/plans/2026-05-11-kilo-organization-selection.md

Builds the Swift package and shows the last 5 lines of output. Expected to succeed after adding the new fields.

```bash
swift build 2>&1 | tail -5
```

--------------------------------

### Configure Git Remotes

Source: https://github.com/steipete/codexbar/blob/main/docs/FORK_SETUP.md

Sets up the fork as origin, adds upstream and quotio remotes, fetches all, and verifies the configuration.

```bash
git remote -v
# Should show: origin  git@github.com:topoffunnel/CodexBar.git

git remote add upstream https://github.com/steipete/CodexBar.git

git remote add quotio https://github.com/nguyenphutrong/quotio.git

git fetch --all

git remote -v
# Should show:
# origin    git@github.com:topoffunnel/CodexBar.git (fetch/push)
# upstream  https://github.com/steipete/CodexBar.git (fetch/push)
# quotio    https://github.com/nguyenphutrong/quotio.git (fetch/push)
```

--------------------------------

### Check for running or installed CodexBar copies

Source: https://github.com/steipete/codexbar/blob/main/docs/keychain-prompts.md

Use these commands to identify other running or installed CodexBar instances during troubleshooting. The pgrep command lists processes matching 'CodexBar|CodexBarCLI', ls checks the standard app location, brew shows Homebrew installation info, and mdfind searches by bundle identifier.

```bash
pgrep -fl 'CodexBar|CodexBarCLI'
ls -ld /Applications/CodexBar.app
brew info --cask codexbar
mdfind 'kMDItemCFBundleIdentifier == "com.steipete.codexbar"'
```

--------------------------------

### Clean Build and Check Formatting

Source: https://github.com/steipete/codexbar/blob/main/docs/FORK_QUICK_START.md

These commands clean the Swift package, build it, and then check for formatting issues using swiftformat and swiftlint. Run them when encountering build errors.

```bash
# Clean build
swift package clean
swift build

# Check for format issues
swiftformat Sources Tests --lint
swiftlint --strict
```

--------------------------------

### Custom provider configuration example (version 2)

Source: https://github.com/steipete/codexbar/blob/main/docs/custom-provider-design.md

Example JSON configuration for a custom HTTP/JSON provider with id 'acme-gateway', kind 'custom-http-json', and mapping for primary, cost, and identity fields. The authentication type is 'bearer', and the secret is read from an environment variable derived from the instance ID.

```json
{
  "version": 2,
  "providers": [
    {
      "id": "acme-gateway",
      "kind": "custom-http-json",
      "label": "Acme Gateway",
      "enabled": true,
      "request": {
        "method": "GET",
        "url": "https://gateway.example.com/v1/quota",
        "authentication": { "type": "bearer" }
      },
      "mapping": {
        "primary": {
          "usedPercent": { "path": "quota.used_pct" },
          "resetsAt": { "path": "quota.reset_at", "dateFormat": "iso8601" },
          "windowMinutes": { "path": "quota.window_minutes" }
        },
        "cost": {
          "used": { "path": "spend.usd" },
          "currency": "USD",
          "period": "Approx. spend"
        },
        "identity": {
          "organization": { "path": "plan.name" },
          "loginMethod": { "literal": "api" }
        }
      }
    }
  ]
}
```

--------------------------------

### Check git status

Source: https://github.com/steipete/codexbar/blob/main/docs/superpowers/plans/2026-05-11-kilo-organization-selection.md

Verify that the working tree is clean before starting implementation.

```bash
git status
```

--------------------------------

### CLI Configuration Shortcuts

Source: https://github.com/steipete/codexbar/blob/main/docs/configuration.md

Common CLI commands for managing providers and setting API keys via standard input.

```bash
codexbar config providers
codexbar config enable --provider grok
codexbar config disable --provider cursor
printf '%s' "$ELEVENLABS_API_KEY" | codexbar config set-api-key --provider elevenlabs --stdin
printf '%s' "$OPENAI_ADMIN_KEY" | codexbar config set-api-key --provider openai --stdin
printf '%s' "$GROQ_API_KEY" | codexbar config set-api-key --provider groq --stdin
printf '%s' "$LLM_PROXY_API_KEY" | codexbar config set-api-key --provider llmproxy --stdin
printf '%s' "$LITELLM_API_KEY" | codexbar config set-api-key --provider litellm --stdin
printf '%s' "$CLAWROUTER_API_KEY" | codexbar config set-api-key --provider clawrouter --stdin
printf '%s' "$SUB2API_API_KEY" | codexbar config set-api-key --provider sub2api --stdin
printf '%s' "$AIAND_API_KEY" | codexbar config set-api-key --provider aiand --stdin
printf '%s' "$XAI_MANAGEMENT_API_KEY" | codexbar config set-api-key --provider xai --stdin
```

--------------------------------

### Run CodexBar with Bedrock provider

Source: https://github.com/steipete/codexbar/blob/main/docs/bedrock.md

Use the CLI to run the Bedrock provider. With --provider bedrock and --source api, the default format is used; with --format json --pretty, JSON output is formatted for readability.

```bash
codexbar --provider bedrock --source api
```

```bash
codexbar --provider bedrock --format json --pretty
```

--------------------------------

### Build to confirm wiring compiles

Source: https://github.com/steipete/codexbar/blob/main/docs/superpowers/plans/2026-05-11-kilo-organization-selection.md

Build command to confirm wiring compiles. Expected to succeed. If `UsageSnapshot.replacingIdentityOrganization` clashes with an existing extension, rename to `withAccountOrganization` and update the call site.

```bash
swift build 2>&1 | tail -15
```

--------------------------------

### GET <baseURL>/api/organization/subscription/usage

Source: https://github.com/steipete/codexbar/blob/main/docs/factory.md

Returns Standard and Premium token usage and billing window for the organization.

```APIDOC
## [GET] <baseURL>/api/organization/subscription/usage

### Description
Returns Standard and Premium token usage and billing window for the organization.

### Method
GET

### Endpoint
<baseURL>/api/organization/subscription/usage

### Parameters
#### Query Parameters
- **useCache** (boolean) - Required - Must be `true`
- **userId** (string) - Optional - User ID to filter usage

### Headers
- **Accept** (string) - Required - Must be `application/json`
- **Content-Type** (string) - Required - Must be `application/json`
- **Origin** (string) - Required - Must be `https://app.factory.ai`
- **Referer** (string) - Required - Must be `https://app.factory.ai/`
- **x-factory-client** (string) - Required - Must be `web-app`
- **Authorization** (string) - Optional - Bearer token or API key when available
- **Cookie** (string) - Optional - Session cookies when available

### Response
#### Success Response (200)
- **standard** (object) - Standard token usage
- **premium** (object) - Premium token usage
- **billingWindow** (object) - Billing window information

#### Response Example
No response example documented.

```

--------------------------------

### GET <baseURL>/api/app/auth/me

Source: https://github.com/steipete/codexbar/blob/main/docs/factory.md

Returns org and subscription metadata plus feature flags for the authenticated user.

```APIDOC
## [GET] <baseURL>/api/app/auth/me

### Description
Returns org and subscription metadata plus feature flags for the authenticated user.

### Method
GET

### Endpoint
<baseURL>/api/app/auth/me

### Headers
- **Accept** (string) - Required - Must be `application/json`
- **Content-Type** (string) - Required - Must be `application/json`
- **Origin** (string) - Required - Must be `https://app.factory.ai`
- **Referer** (string) - Required - Must be `https://app.factory.ai/`
- **x-factory-client** (string) - Required - Must be `web-app`
- **Authorization** (string) - Optional - Bearer token or API key when available
- **Cookie** (string) - Optional - Session cookies when available

### Response
#### Success Response (200)
- **org** (object) - Organization metadata
- **subscription** (object) - Subscription metadata
- **featureFlags** (object) - Feature flags

#### Response Example
No response example documented.

```

--------------------------------

### Initial Quotio Analysis

Source: https://github.com/steipete/codexbar/blob/main/docs/FORK_SETUP.md

Analyzes the quotio repository and creates a quotio-analysis-YYYYMMDD.md file for review.

```bash
./Scripts/analyze_quotio.sh

# Creates: quotio-analysis-YYYYMMDD.md
# Review the file for interesting patterns
```

--------------------------------

### Run CLI and menu card tests

Source: https://github.com/steipete/codexbar/blob/main/docs/superpowers/plans/2026-05-11-kilo-organization-selection.md

Runs the CLI snapshot and menu card model tests to verify the change visually without a UI. Existing tests must continue to pass.

```bash
swift test --filter CLIRendererTests 2>&1 | tail -15
```

```bash
swift test --filter MenuCardModelTests 2>&1 | tail -15
```

--------------------------------

### One-shot CLI command: codexbar dashboard

Source: https://github.com/steipete/codexbar/blob/main/docs/dashboard-api.md

Outputs a single JSON document to stdout and exits. Starts no server and requires no token.

```bash
# One JSON document on stdout, then exit
codexbar dashboard
```

--------------------------------

### GET https://api.kimi.com/coding/v1/usages

Source: https://github.com/steipete/codexbar/blob/main/docs/kimi.md

Retrieves the current usage limits and consumption for the Kimi Code API. This endpoint requires a Bearer token for authentication.

```APIDOC
## GET https://api.kimi.com/coding/v1/usages

### Description
Retrieves the current usage limits and consumption for the Kimi Code API. This endpoint requires a Bearer token for authentication.

### Method
GET

### Endpoint
https://api.kimi.com/coding/v1/usages

### Authentication
Bearer token (from `providers[].apiKey`, `KIMI_CODE_API_KEY`, or a fresh Kimi Code CLI credential)

### Response
#### Success Response (200)
- **usage** (object) - Contains the overall usage details.
  - **limit** (string) - The total limit.
  - **used** (string) - The amount used.
  - **remaining** (string) - The remaining amount.
  - **resetTime** (string) - The reset time in ISO 8601 format.
- **limits** (array) - A list of usage limits for specific windows.
  - **window** (object) - The time window details.
    - **duration** (integer) - The duration of the window.
    - **timeUnit** (string) - The time unit (e.g., TIME_UNIT_MINUTE).
  - **detail** (object) - The usage details for the window.
    - **limit** (string) - The limit for the window.
    - **used** (string) - The used amount.
    - **remaining** (string) - The remaining amount.
    - **resetTime** (string) - The reset time.

#### Response Example
{
  "usage": {
    "limit": "2048",
    "used": "214",
    "remaining": "1834",
    "resetTime": "2026-01-09T15:23:13.716839300Z"
  },
  "limits": [{
    "window": {"duration": 300, "timeUnit": "TIME_UNIT_MINUTE"},
    "detail": {
      "limit": "200",
      "used": "139",
      "remaining": "61",
      "resetTime": "2026-01-06T13:33:02.717479433Z"
    }
  }]
}
```

--------------------------------

### GET https://api.factory.ai/api/billing/limits

Source: https://github.com/steipete/codexbar/blob/main/docs/factory.md

Retrieves billing limits for the account, preferred when the account uses token-rate-limits billing (5h / weekly / monthly windows).

```APIDOC
## [GET] https://api.factory.ai/api/billing/limits

### Description
Retrieves billing limits for the account, preferred when the account uses token-rate-limits billing (5h / weekly / monthly windows).

### Method
GET

### Endpoint
https://api.factory.ai/api/billing/limits

### Headers
- **Accept** (string) - Required - Must be `application/json`
- **Content-Type** (string) - Required - Must be `application/json`
- **Origin** (string) - Required - Must be `https://app.factory.ai`
- **Referer** (string) - Required - Must be `https://app.factory.ai/`
- **x-factory-client** (string) - Required - Must be `web-app`
- **Authorization** (string) - Optional - Bearer token or API key when available
- **Cookie** (string) - Optional - Session cookies when available

### Response
#### Success Response (200)
- No response schema documented.

#### Response Example
No response example documented.

```

--------------------------------

### Sign and Notarize Script

Source: https://github.com/steipete/codexbar/blob/main/docs/RELEASING.md

Executes the full release pipeline including universal builds, code signing, notarization, and packaging.

```bash
./Scripts/sign-and-notarize.sh
```

--------------------------------

### Example quota_reached event payload

Source: https://github.com/steipete/codexbar/blob/main/docs/configuration.md

This JSON object represents the payload sent to the hook executable via stdin when a quota_reached event occurs.

```json
{"event":"quota_reached","provider":"claude","resetAt":"2023-11-14T22:13:20Z","timestamp":"2023-11-14T22:15:00Z","usagePercent":0.42,"window":"session"}
```

--------------------------------

### Quick Build Without Tests

Source: https://github.com/steipete/codexbar/blob/main/docs/DEVELOPMENT_SETUP.md

Builds in release mode and packages the app without running tests.

```bash
swift build -c release
./Scripts/package_app.sh
```

--------------------------------

### ZoomMate API GET requests

Source: https://github.com/steipete/codexbar/blob/main/docs/zoommate.md

Endpoints used by CodexBar to fetch credit status and history. Automatic requests retry on zoommate.zoom.us if ai.zoom.us fails.

```text
GET https://ai.zoom.us/ai-computer/api/v1/credits/status
GET https://ai.zoom.us/ai-computer/api/v1/credits/history?app_id=demo_app&limit=50&page=<n>&sort_by=time&sort_order=desc&start_time=<ISO8601>&end_time=<ISO8601>
```

--------------------------------

### Local Development Build: package_app.sh

Source: https://github.com/steipete/codexbar/blob/main/docs/DEVELOPMENT.md

Runs the packaging script to create CodexBar.app with ad-hoc signing by default. Use this for local development builds.

```bash
./Scripts/package_app.sh
# Creates: CodexBar.app with ad-hoc signing by default
```

--------------------------------

### Upstream-bound commit message example

Source: https://github.com/steipete/codexbar/blob/main/docs/UPSTREAM_STRATEGY.md

Use for commits that are generic and suitable for upstream submission. The message describes the bug fix and includes testing notes.

```text
fix: correct Cursor bonus credits calculation

The bonus credits were being added instead of subtracted
from the total usage calculation.

Tested with Pro and Team accounts.
```

--------------------------------

### Build and Run Scripts

Source: https://github.com/steipete/codexbar/blob/main/docs/DEVELOPMENT.md

Commands for building, testing, packaging, and launching the CodexBar application.

```bash
# Full build, package, and launch (recommended)
./Scripts/compile_and_run.sh

# Also run the sharded test suite before packaging/relaunching
./Scripts/compile_and_run.sh --test

# Just build and package (no tests)
./Scripts/package_app.sh

# Launch existing app (no rebuild)
./Scripts/launch.sh
```

--------------------------------

### Manual Cookie Provider Configuration

Source: https://github.com/steipete/codexbar/blob/main/docs/configuration.md

Example configuration for a provider using manual cookies. The cookieHeader should contain the HTTP Cookie request header value.

```json
{
  "version": 1,
  "providers": [
    {
      "id": "example-provider",
      "enabled": true,
      "cookieSource": "manual",
      "cookieHeader": "session=<REDACTED>; other=<REDACTED>"
    }
  ]
}
```
Tokens:
Raw