CodexUsage

A small open-source macOS menu bar app that shows Codex 5-hour usage as a percentage and bar.

Download latest DMG · MIT License

한국어 문서는 README.ko.md를 참고하세요.

Download And Install

1. Download the latest CodexUsage.dmg.
2. Open the DMG.
3. Read READ BEFORE INSTALL - Open Anyway Guide.txt inside the DMG.
4. Double-click CodexUsage.app.

If macOS shows "CodexUsage" Not Opened, open System Settings > Privacy & Security, click Open Anyway for CodexUsage, then double-click CodexUsage.app again.

On first launch from the DMG, CodexUsage copies itself to ~/Applications/CodexUsage.app, starts the installed copy, creates a login item, and links the CLI at ~/.codexusage/bin/codexusage.

CodexUsage does not edit your Codex config.toml or Codex status line.

Open Source

CodexUsage is released as an open-source project under the MIT License.

The repository includes:

• Swift source code for the macOS menu bar app.
• DMG build and GitHub release scripts.
• The SVG product icon at docs/assets/codexusage-icon.svg.
• English and Korean installation docs.
• Self-installing app launch from the DMG.

Issues and pull requests are welcome at Wordbe/codex-usage.

Security issues should be reported privately. See SECURITY.md.

Build

swift build -c release
scripts/build-dmg.sh 0.1.3

The DMG is written to dist/CodexUsage-0.1.3.dmg.

CLI

~/.codexusage/bin/codexusage status
~/.codexusage/bin/codexusage status --json
~/.codexusage/bin/codexusage status --refresh
~/.codexusage/bin/codexusage status --diagnose

If the GUI app cannot find Codex, set:

export CODEXUSAGE_CODEX_PATH="$(command -v codex)"

Usage Source And Sync

CodexUsage prefers the same session rate-limit event that Codex /status uses:

~/.codex/sessions/**/*.jsonl
event_msg.payload.rate_limits.primary.used_percent

If no current session event is available, CodexUsage falls back to:

codex app-server --stdio
account/rateLimits/read
rateLimitsByLimitId.codex.primary.usedPercent

The primary window is the 5-hour Codex limit. The app displays current 5-hour usage, not weekly usage.

Cache file:

~/.codexusage/cache/rate-limits.json

Other CodexUsage files are also kept under ~/.codexusage, except the macOS login item plist, which must live in ~/Library/LaunchAgents.

Policy:

• App syncs every 60 seconds.
• Cache TTL is 30 seconds.
• ~/.codexusage/bin/codexusage status --refresh forces a fresh sync.
• ~/.codexusage/bin/codexusage status --diagnose compares app-server, cache, and the latest Codex session token_count rate-limit event.

GitHub Release

After this directory is a GitHub repository with an origin remote:

scripts/release-github.sh v0.1.3