codex-island
CodexIsland - AI usage limits in your MacBook notch
What is it?
What it is
CodexIsland is a native macOS accessory app that overlays the MacBook notch (or menu bar) with a Dynamic‑Island‑style panel showing real‑time usage limits and cost estimates for Claude Code and Codex. It peeks on hover, expands on click, and reads credentials and session logs locally without sending any data off‑device.
Why it exists
It gives developers a privacy‑first, zero‑telemetry way to monitor their AI usage and spending directly on the Mac, without relying on web dashboards or external services, and it integrates seamlessly with existing CLI/desktop tools.
Who should use it
macOS users who frequently use Claude or Codex, privacy-conscious individuals, developers tracking AI usage costs, and tech-savvy users comfortable with open-source tools
Who should avoid it
non-macOS users, users who don't use Claude/Codex, those uninterested in tracking usage limits, and users uncomfortable with unsigned apps
How it works
A quick walkthrough in plain English
How codex-island works
Step 1 of 3
You interact with it
Open codex-island, send a request, or connect it to your stack.
Features
Advantages
- Free and open-source with MIT license
- Local-first design with no external dependencies
- Privacy-focused (no telemetry, analytics, or proxy services)
- Seamless integration with macOS notch and menu bar
- Auto-updates with verified signed builds
- Universal binary support for arm64 and x86_64
- Configurable token counting and chart styles
- No manual credential entry required
- Low Power Mode optimization
- Hover and swipe interactions for efficient use
- Custom settings without system-level integration
Disadvantages
- Unsigned builds require Gatekeeper quarantine bypass
- Relies on undocumented provider endpoints
- Partial multi-monitor support (single island per display)
- No sub-5-minute polling due to provider rate limits
- Synthesized Sparkline history not provider-sourced
- Requires prior Claude/Codex CLI or desktop app setup
- No high-contrast accessibility variant
- Limited token counting options (all or billable)
- No Dock icon for quick access
- Potential future endpoint changes may break functionality
Installation
native
brew install --cask ericjypark/tap/codexisland
FAQ
How do I install CodexIsland?
Install via Homebrew: `brew install --cask ericjypark/tap/codexisland`. Alternatively, download the DMG from Releases, drag the app to /Applications, then run `xattr -dr com.apple.quarantine /Applications/CodexIsland.app` to remove the quarantine attribute (or use 'Open Anyway' in System Settings -> Privacy & Security).
Why do I see 'auth required — run claude' or 'no codex auth'?
For Claude: run `claude` once in Terminal or open Claude Desktop to populate credentials. For Codex: sign in to Codex/ChatGPT CLI so `~/.codex/auth.json` exists. The app reads existing credentials from your system; it does not ask for new ones.
How does CodexIsland get my usage data?
It reads credentials already written by Claude Code/Claude Desktop and Codex, then calls the providers' own usage endpoints: for Claude, it checks `CLAUDE_CODE_OAUTH_TOKEN`, the macOS Keychain, or refreshes via Anthropic's OAuth endpoint; for Codex, it reads `~/.codex/auth.json`. No extra auth is needed.
Why can't I set a refresh interval shorter than 5 minutes?
Anthropic rate-limits the `/api/oauth/usage` endpoint aggressively per token. The app only offers 5m, 15m, and 30m intervals to avoid being blocked; sub-5-minute polling is not available.
Does CodexIsland work on Macs without a notch?
Yes. On non-notched Macs, it falls back to a 200x28 menu-bar pill. The notch-native overlay is only used on Macs with a physical notch; otherwise, it appears in the menu bar area.
Featured in Videos
YouTube tutorials and walkthroughs for codex-island
Alternatives
Similar projects ranked by category, topics, and text overlap.
