CC-Overlay

한국어 | Release Notes (한국어) | Contributing | Security

macOS menu bar app that monitors your Claude Code and Codex CLI usage in real time.

CC-Overlay is an independent, open-source utility distributed directly through GitHub Releases and Homebrew. It is not affiliated with, endorsed by, or supported by Anthropic or OpenAI.

Features

• Multi-provider monitoring — Track Claude Code and OpenAI Codex CLI usage simultaneously
• Authenticated-only display — Unconfigured providers never appear as misleading setup or usage indicators
• Live rate-limit windows — 5-hour and 7-day rate-limit data from Claude Code and Codex OAuth
• Local fallback, clearly labeled — Claude JSONL estimates are marked with ~ and "local estimate"
• Floating Liquid Glass overlay — A compact, screen-bounded status surface that expands on hover
• Pacing signals — 5H and 7D timelines distinguish fast burn, on-pace, and plenty-left states
• Provider switcher — A compact selector appears only when both providers have usable data
• Cost threshold alerts — macOS notifications at 70% and 90% usage
• Global hotkey — Toggle overlay with Cmd+Shift+A

Distribution and Trust

Tagged releases are built as universal Apple Silicon and Intel app bundles, signed with a Developer ID Application certificate using the hardened runtime, notarized by Apple, and stapled before publication. The release workflow also validates the app signature, bundle contents, clean archive, and SHA-256 checksum.

Homebrew installs the signed CC-Overlay.app bundle without re-signing it. Verify an installed release with:

APP="$(brew --prefix cc-overlay)/CC-Overlay.app"
codesign --verify --deep --strict --verbose=2 "$APP"
spctl --assess --type execute --verbose=4 "$APP"

For a manual GitHub Release download, verify the published checksum before opening the archive:

shasum -a 256 -c CC-Overlay-vX.Y.Z-macos.zip.sha256

Local builds created with script/build_and_run.sh are ad-hoc signed for development. They are not release artifacts.

Install

Homebrew

brew tap jadru/cc-overlay
brew install cc-overlay
cc-overlay

Enable Launch at login from the app's Settings when you want it to start with macOS. CC-Overlay deliberately does not install a Homebrew background service, so it has one app process and one login-start mechanism.

If you upgraded from 0.8.x, remove its legacy Homebrew service once:

launchctl bootout "gui/$(id -u)" ~/Library/LaunchAgents/homebrew.mxcl.cc-overlay.plist 2>/dev/null || true
rm -f ~/Library/LaunchAgents/homebrew.mxcl.cc-overlay.plist
brew upgrade cc-overlay

Uninstall

Turn off Launch at login in Settings first, then remove the app:

brew uninstall cc-overlay

Build from source

Requires Swift 6.0+ and macOS 15+ (Sequoia) SDK.

git clone https://github.com/jadru/homebrew-cc-overlay.git
cd homebrew-cc-overlay
./script/build_and_run.sh

To exercise the same universal packaging checks used by CI without notarization:

VERSION=0.0.0 BUILD_NUMBER=0 SIGN_IDENTITY=- NOTARIZE=0 ARCHS="arm64 x86_64" ./script/package_release.sh

Usage

Run cc-overlay — the app lives in the menu bar. Click the menu bar icon to see detailed usage or open Settings.

Data sources

Privacy and Provider Access

CC-Overlay has no developer-operated backend and does not upload usage history or OAuth credentials to the project maintainer. It makes outbound requests only to the selected provider's usage endpoint and to GitHub Releases when update checks are enabled.

• Codex usage reads the local Codex CLI authentication file to make a direct request to the provider's usage endpoint.
• Claude transcript estimates read recent local JSONL files. Claude OAuth rate-limit access is off by default and requires an explicit Settings opt-in.
• Usage history, settings, and diagnostic logs stay on the local Mac.

Provider tokens are sensitive. Review the source and use a release you trust before enabling a provider. This project is an unofficial integration and provider APIs, limits, and authentication formats may change without notice.

Menu bar dropdown

The dropdown shows the selected provider's usage timeline. When both providers have
data, a compact provider switcher is shown above it. Each primary window presents
used and remaining capacity, reset timing, and a pace assessment.

Floating pill

The overlay shows the most constrained provider. It stays inside the active screen
when expanded and shows 5H/7D pace meters. A local estimate is prefixed with ~.

Configuration

All settings persist via UserDefaults and are accessible from the Settings window (menu bar > Settings).

Model pricing

Cost estimates use the following per-MTok rates:

License

MIT

Provider names and marks are the property of their respective owners. Their use here is solely to identify compatible tools.