Bringing AI to the Mac Menu Bar: A Deep Dive into the AI Usa

Introduction

Artificial intelligence has become a daily companion for many developers, especially with the rise of large language models like Claude (Anthropic) and Codex (OpenAI). While these models offer powerful code‑generation capabilities, they also introduce new operational concerns: token consumption, request limits, and cost tracking. Until now, most developers have relied on web dashboards or verbose terminal output to keep tabs on their usage.

Enter AI Usage – Native macOS Menu Bar for Claude Code and Codex Limits – a concise, open‑source project hosted on GitHub that places real‑time AI metrics directly in the macOS menu bar. In this post we’ll explore the motivation behind the tool, its core architecture, how you can get it running on your machine, and why such a tiny UI element can have a big impact on developer productivity.

---

Why a Menu‑Bar Widget?

The macOS menu bar is a proven spot for quick‑glance information: battery level, Wi‑Fi strength, calendar events, and even third‑party utilities like iStat Menus. By leveraging this space, the AI Usage widget eliminates the need to switch contexts. Instead of opening a browser tab or scrolling through terminal logs, a single glance tells you:

- How many Claude Code tokens you have consumed today. - The remaining request quota for Codex. - A simple visual cue (green/yellow/red) indicating whether you are approaching your limits.

This design philosophy aligns with the broader trend of context‑preserving tools—software that surfaces relevant data exactly where you need it, without disrupting your workflow.

---

Core Features

| Feature | Description | |---------|-------------| | Claude Code token counter | Pulls daily usage stats from Claude’s API and displays the total tokens used versus the plan limit. | | Codex request limit monitor | Shows the number of remaining Codex completions for the current billing period. | | Customizable thresholds | Users can set warning levels (e.g., 80 % of the quota) to trigger a color change in the menu bar icon. | | Zero‑config launch | After a one‑time API‑key setup, the app runs silently in the background, updating every 5 minutes. | | Open‑source and extensible | Written in Swift, the codebase invites contributions—add support for other models, integrate Slack notifications, or tweak the UI. |

---

Architecture at a Glance

The project follows a minimalistic architecture that keeps the binary lightweight (≈ 7 MB) and the runtime overhead negligible.

1. SwiftUI + AppKit – The UI is built with SwiftUI for the pop‑over view and AppKit’s NSStatusItem for the menu‑bar icon. 2. Background fetcher – A Timer scheduled on a background queue calls the Claude and Codex endpoints every 300 seconds. 3. Secure storage – API keys are stored in the macOS Keychain, ensuring they never touch plain‑text files. 4. JSON parsing – Simple Codable structs map the API responses to Swift objects, avoiding heavyweight third‑party libraries. 5. Configuration file – A small plist in ~/Library/Application Support/ai‑usage‑menubar/ holds user preferences (refresh interval, thresholds, etc.).

The entire flow can be visualized as:

` [Timer] → [Network Layer] → [Parse JSON] → [Update Model] → [Refresh NSStatusItem] `

---

Getting Started

Below is a step‑by‑step guide to bring the widget onto your Mac.

`bash ## 1. Clone the repository git clone https://github.com/burakgon/ai-usage-menubar.git cd ai-usage-menubar

2. Open the Xcode project (requires Xcode 15+) open AIUsageMenubar.xcodeproj

3. Add your API keys ## - Open the app’s Preferences window (⌘+,) after the first build. ## - Paste your Claude and Codex keys into the secure fields.

4. Build & Run ## Press ⌘R – the menu‑bar icon should appear next to the clock. ```

> Tip: If you prefer a pre‑built binary, the releases page provides a signed .app bundle that can be dragged into /Applications.

---

Extending the Utility

Because the code is open source, adding new providers is straightforward:

1. Create a new service protocol – Define a UsageProvider protocol with fetchUsage(completion:). 2. Implement the protocol – Write a Swift class that contacts the new API, parses the response, and returns a unified UsageMetrics struct. 3. Register the provider – Add the class to the ProviderRegistry used by the background fetcher. 4. Update the UI – Extend the pop‑over view to display the new metrics.

Community contributions have already started a fork that adds GitHub Copilot usage stats, demonstrating the flexibility of the design.

---

The Bigger Picture: UI‑First AI Ops

The AI Usage menubar is more than a convenience; it signals a shift toward UI‑first AI operations (AI‑Ops). Historically, developers have managed AI consumption through logs and dashboards, which adds friction and can lead to unexpected cost overruns. By surfacing key metrics at the OS level, we:

- Reduce cognitive load – No need to memorize token limits; the UI does it for you. - Encourage responsible usage – Visual warnings prompt developers to refactor prompts or batch requests. - Enable rapid iteration – Immediate feedback lets you experiment with model parameters without worrying about hidden costs.

As AI models become ubiquitous across tooling, expect more native integrations—think system‑wide shortcuts for prompting, desktop notifications for quota breaches, and even menu‑bar controls to toggle model versions.

---

Conclusion

The AI Usage – Native macOS Menu Bar project transforms abstract usage data into a tangible, always‑visible cue. Its lightweight implementation, secure handling of credentials, and extensible architecture make it a valuable addition to any developer’s toolkit. Whether you are a solo coder watching token spend or part of a team managing shared API budgets, this menubar widget offers a simple yet powerful way to stay in control.

Give it a try, fork the repo, and consider what other AI‑related signals could benefit from a menu‑bar presence. The future of developer ergonomics may just be a few pixels away.

---

Happy coding, and may your token usage stay green!

Sources: https://github.com/burakgon/ai-usage-menubar