sub-bar

Usage widget extension for pi-coding-agent.

Displays current provider usage in a widget below the editor. Fetching and caching are handled by sub-core.

Impressions

https://github.com/user-attachments/assets/d61d82f6-afd0-45fc-82f3-69910543aa7a

Overview

Features

• Displays realtime usage quotas for multiple AI providers
• Auto-detects provider from current model (via sub-core)
• Shows rate limit windows with visual progress bars
• Status indicators from provider status pages
• Theme save/share/import and sub-bar:import preview flow
• Provider Shown selector to pin the displayed provider
• Extensive settings UI via sub-bar:settings
• Cycle through providers with Ctrl+Alt+P

Supported Providers

| Provider | Usage Data | Status Page | |----------|-----------|-------------| | Anthropic (Claude) | 5h/Week windows, extra usage | ✅ | | GitHub Copilot | Monthly quota, requests | ✅ | | Google Gemini | Pro/Flash quotas | ✅ | | Antigravity | Model quotas | ✅ | | OpenAI Codex | Primary/secondary windows | ✅ | | AWS Kiro | Credits | - | | z.ai | Tokens/monthly limits | - |

Provider Feature Matrix

| Provider | Usage Windows | Extra Info | Status Indicator | Tested | Notes | |----------|--------------|------------|------------------|--------|-------| | Anthropic (Claude) | 5h, Week, Extra | Extra usage label | ✅ | ✅ | Extra usage can show on/off state | | GitHub Copilot | Month | Model multiplier + requests left | ✅ | ✅ | Requests left uses model multiplier | | Google Gemini | Pro, Flash | - | ✅ | - | Quotas aggregated per model family | | Antigravity | Models | - | ✅ | ✅ | Sandbox Cloud Code Assist quotas | | OpenAI Codex | Primary, Secondary | - | ✅ | ✅ | Credits not yet supported (PRs welcome!) | | AWS Kiro | Credits | - | - | - | - | | z.ai | Tokens, Monthly | - | - | - | API quota limits |

Installation

Install via the pi package manager (recommended). sub-bar bundles sub-core, so you only need to install sub-bar:

pi install npm:@marckrenn/pi-sub-bar

Use -l to install into project settings instead of global:

pi install -l npm:@marckrenn/pi-sub-bar

If you previously installed sub-core separately, remove it from ~/.pi/agent/extensions or ~/.pi/agent/settings.json to avoid duplicate core instances.

Manual install (local development):

git clone https://github.com/marckrenn/pi-sub.git
cd pi-sub
npm install

ln -s /path/to/pi-sub/packages/sub-bar ~/.pi/agent/extensions/sub-bar

For local development, also ensure sub-core is available (either link it separately or link it into packages/sub-bar/node_modules).

Alternative (no symlink): add sub-bar to ~/.pi/agent/settings.json:

{
  "extensions": [
    "/path/to/pi-sub/packages/sub-bar/index.ts"
  ]
}

Usage

The extension loads automatically. Use:

• sub-bar:settings - Open display + provider UI settings (includes Provider Shown)
• sub-bar:import <share string> - Preview a shared theme and choose to save/apply
• sub-core:settings - Configure provider enablement/order + usage/status refresh settings
• Ctrl+Alt+P - Cycle through available providers (configurable)
• Ctrl+Alt+R - Toggle reset timer format (configurable)

Keybindings:

Shortcuts are configurable via sub-bar:settings → Keybindings. Enter any valid key combo (e.g. ctrl+alt+p, ctrl+shift+s) or none to disable a shortcut. Keybinding changes take effect after pi restart.

Caching:

• Handled by sub-core at ~/.pi/agent/cache/sub-core/cache.json
• Cache TTL matches your auto-refresh interval setting
• Lock file prevents race conditions between multiple pi windows

Communication with sub-core

sub-bar is a display client. It listens for sub-core:update-current/sub-core:ready events and renders the widget. On startup it requests the current state via sub-core:request.

sub-bar manages display settings and UI-only provider options (window visibility, labels, status indicator). Provider enablement lives in sub-core, but the sub-bar settings UI can toggle Enabled (auto/on/off) and forwards changes to sub-core:settings:patch. Ordering and refresh behavior are configured in sub-core:settings, and sub-core broadcasts updates that sub-bar consumes. The cycle command forwards to sub-core:action so core updates provider selection and then broadcasts the new state.

Settings

Display and provider UI settings are stored in ~/.pi/agent/pi-sub-bar-settings.json (migrated from the legacy extension settings.json when present; the legacy file is removed after a successful migration). Core settings are managed by sub-core, and the sub-bar settings menu includes a shortcut that points you to sub-core:settings for additional options.

Settings migrations: settings are merged with defaults on load, but renames/removals are not migrated automatically. When adding new settings or changing schema, update the defaults/merge logic and provide a migration (or instruct users to reset pi-sub-bar-settings.json).

Provider UI Settings

Use sub-bar:settings → Provider Settings to control enabled state (auto/on/off), status indicators, and per-provider window visibility.

Core Settings

Use sub-core:settings to configure provider enablement (auto/on/off), fetch status, usage refresh settings, status refresh settings, and provider order.

Display Settings

Use Display Settings → Theme to save, load, import, and randomize display themes.

Display Settings cover layout, bars, labels/text, reset timers, status indicators, dividers, and color tuning. Open sub-bar:settings → Display Settings to explore the full list in the UI.

Credentials

Credentials are loaded by sub-core from:

• ~/.pi/agent/auth.json - pi's auth file
• Provider-specific locations (e.g., ~/.codex/auth.json, ~/.gemini/oauth_creds.json)
• macOS Keychain for Claude Code credentials
• Environment variables (e.g., Z_AI_API_KEY)

Development

Packaging notes (pi install compatibility)

Pi packages use a pi field in package.json plus the pi-package keyword for discoverability. This repo already declares pi.extensions, so you can install via:

pi install npm:@marckrenn/pi-sub-core
pi install npm:@marckrenn/pi-sub-bar

Manual paths/symlinks still work for local development as documented above.

Architecture

sub-bar/
├── index.ts              # Extension entry point (display client)
├── src/
│   ├── formatting.ts     # UI formatting
│   ├── status.ts         # Status indicator helpers
│   ├── utils.ts          # Display helpers
│   ├── providers/        # Display metadata + visibility rules
│   ├── settings/         # Settings UI helpers
│   ├── settings-types.ts # Settings type definitions
│   ├── settings.ts       # Settings persistence
│   └── usage/types.ts    # Shared usage types
├── package.json
└── tsconfig.json

Adding a New Provider

Update both sub-core (fetch) and sub-bar (display). See sub-core/README.md for the full checklist.

Feature placement (UI vs core)

• sub-bar owns presentation (formatting, layout, status indicators, UI settings).
• sub-core owns data fetching, caching, provider selection, and shared settings/events.
• Add shared types to sub-shared when both layers reference them.

See the root README “Developer guide” for the full decision checklist and examples.

Commands

npm run check

Credits

• ~Hannes~ Helmut Januschka (usage-bar.ts, @hjanuschka)
• Peter Steinberger (CodexBar, @steipete)

License

MIT