AI Usage Monitor

A native macOS notch/menu utility for monitoring AI usage across providers and local agent tools.

The current product direction and acceptance criteria are documented in docs/superpowers/specs/2026-07-11-three-layer-monitor-architecture-design.md.

The current app includes:

• A compact Notch surface for verified Active and Needs reply counts.
• An expanded Notch view for conversations, provider-scoped usage, and one Dashboard entry.
• A four-destination Dashboard: Overview, Agents, Providers, and Settings.
• Provider detail pages for Summary, Usage, Quota, and Diagnostics.
• Local source adapters plus optional direct provider API refreshes.
• Verified Codex subscription windows from a short-lived, signed local Codex app-server process.
• Strictly separate additive usage events and latest-only quota snapshots.

The intended product model has three independent layers:

• Provider Usage keeps PAYG/local additive usage separate from latest-only subscription quota snapshots.
• Agent Activity uses verified live thread state when a supported runtime transport is available; local transcript recency is inferred history, not Active.
• Source Diagnostics contains paths, authentication, trust, freshness, and errors without turning internal sources into primary navigation.
• Cost is an optional separate projection, not the main gauge and not quota.
• Data is stored locally. Official provider APIs can still be called directly from the user's Mac when enabled.

The primary interface target is native macOS 27 Liquid Glass. Standard NavigationSplitView, sidebar, toolbar, search, materials, and controls are preferred over custom blur or hand-painted glass. The physical Notch remains an opaque black hardware extension, with availability-guarded native Material fallbacks on earlier supported macOS releases.

Run in development

swift run AIUsageMonitor

Build the notch utility app bundle

make app
open "dist/AI Usage Monitor.app"

The app bundle is configured as LSUIElement, so it stays out of the Dock. The Notch is the persistent entry point; the app does not create a separate menu bar status item.

Connector notes

macOS cannot reliably infer token usage and spend from every AI app by itself. Production monitoring usually needs one or more of:

• Direct billing or usage APIs from each provider.
• CSV exports from products that do not expose APIs.
• Local client transcript/session sources for client activity.
• Team workspace integrations for enterprise products.

Codex session logs can contain self-reported per-turn token-count events, so they are useful verified-client usage history, but they are not full account billing truth. Local session files provide inferred thread history only. Live Codex Desktop Active and Needs reply status requires a documented attachable runtime transport; when one is unavailable the app reports live status as unavailable instead of inferring it from file activity. Provider APIs remain the preferred source for provider-level usage where available.

Codex subscription limits use a separate adapter. It launches a short-lived read-only app-server from an OpenAI-signed Codex executable, reads account rate limit windows, and then terminates the child. Those percent windows are stored as latest-only verified-provider snapshots. They are not converted to token counts and are not treated as the live thread registry of Codex Desktop. The experimental protocol is version-probed and fails closed on incompatible data.

The app should not require a hosted backend, server-side provider proxy, or cloud sync for the MVP.