Skip to content

research.md

Latest commit

 

History

History
78 lines (62 loc) · 3.64 KB

research.md

File metadata and controls

78 lines (62 loc) · 3.64 KB
Raw

Left research

(Recorded while the app was called UsageBar; see docs/naming.md.)

Research date: 2026-07-26

Decision

Build a small native macOS menu-bar app around quota-axi's normalized JSON. Keep the quota command behind a Swift protocol so another normalized source can replace it without changing the UI.

This reuses the provider work that already exists while avoiding a second auth implementation. The app never receives credentials on its command line, never requests --full output, and never writes command output to disk or logs.

Evidence

quota-axi

  • The installed executable is quota-axi 0.1.6 from the kunchenguid/quota-axi npm package. GitHub's latest public release is 0.1.13, published 2026-07-25.
  • Its schema-version 2 JSON normalizes provider identity, plan, usage windows, remaining percentage, reset time, freshness, errors, retry state, and repair guidance.
  • It supports Claude, Codex, Cursor, Copilot, Grok, and Kimi. Claude and Codex expose the exact session, weekly, and model-scoped windows this prototype needs.
  • Plain reads call first-party provider endpoints using existing local auth. The --full flag is the only mode that includes account identity and source attempts. Left does not pass that flag.
  • A plain Claude read avoids a Keychain prompt. If the file credential expires, quota-axi reports stale or unavailable data with keychain_access_required; the user can grant access separately.
  • The local 0.1.6 binary returned schema-version 2 data for both target providers. Unknown fields from newer versions remain safe because Swift's decoder ignores them.

quota-axi is the local quota command Left wraps. It has no menu-bar view; Left is that view.

Peter Steinberger's CodexBar

steipete/CodexBar is no longer Codex-only. At research time it has about 19,000 stars, an active Swift codebase, a 0.45.2 release from 2026-07-19, Homebrew installation, and dozens of providers. It offers polished status items, reset countdowns, provider strategies, and error diagnostics.

CodexBar is the best maintained complete product in this category. It is not the right base for this bounded prototype because its large provider and auth stack duplicates quota-axi; adopting it would make the requested normalized layer incidental. Its provider descriptor and fetch-strategy separation support the adapter boundary chosen here.

Maintained alternatives

  • erikgaal/claude-usage-menu-bar is an active native Swift app for Claude and Codex. It implements separate OAuth flows and stores its own tokens in Keychain. That adds credentials and duplicates the installed quota layer.
  • HemSoft/codexbar-mac is an active pre-release native Swift app with eight providers. It also implements local, browser OAuth, and API-key paths itself.
  • akitaonrails/ai-usagebar is a maintained multi-provider Rust project for Linux Waybar, not a macOS menu-bar app.
  • A SwiftBar plugin would be smaller than a native app, but it would require a separate menu-bar host and constrain stale/error presentation.

Prototype boundary

The prototype uses AppKit for the status item and SwiftUI for the dropdown. It has no third-party runtime dependency beyond quota-axi. The installer builds an application bundle with the installed Swift toolchain and copies it to a chosen destination. The repository fixture drives demo mode, tests, and the preview image without touching subscription credentials.