Codex Weekly

English | 简体中文

A lightweight native macOS menu bar utility that displays the current Codex account's rolling five-hour quota, weekly quota, and both reset times.

This is an independent community project. It is not affiliated with, endorsed by, or sponsored by OpenAI.

Features

• Shows the rolling five-hour quota directly in the menu bar
• Shows five-hour and weekly usage/reset details in the menu
• Refreshes every 60 seconds, with manual refresh support
• Automatically adapts to light, dark, and fullscreen menu bar backgrounds
• Uses a warning symbol for low quota instead of relying on fixed colors
• Shows the used percentage and next reset time
• Optional launch at login
• Native multi-resolution macOS app icon
• Does not read, copy, or upload ~/.codex/auth.json; quota data is retrieved through the local Codex CLI app-server

Installation

1. Download Codex-Weekly-macOS.zip from the latest release.
2. Extract the archive.
3. Move Codex Weekly.app to /Applications.
4. Launch the app. It runs in the menu bar and does not appear in the Dock.
5. If macOS blocks the non-notarized community build, right-click the app in Finder and choose Open.

Codex Desktop or Codex CLI must already be installed and signed in.

Build and Verify

./build-app.sh
.build/release/CodexWeekly --probe

Build artifacts are written to dist/. Building requires macOS 13+ and Xcode/Swift 6.

How It Works

The app starts the local Codex CLI with app-server --stdio, calls account/rateLimits/read, and parses both the 300-minute rolling five-hour window and the 10,080-minute weekly window.

• Does not directly read ~/.codex/auth.json
• Does not copy or upload Codex tokens
• Contains no analytics, telemetry, or third-party network requests
• All quota access is handled locally by the Codex CLI

The Codex CLI app-server is experimental, so future protocol changes may require updates.

Development

swift test
swift run CodexWeekly --probe

Project structure:

• CodexQuotaClient.swift: Codex app-server communication
• QuotaSnapshot.swift: five-hour and weekly quota parsing and window selection
• AppDelegate.swift: menu bar UI, refresh scheduling, and launch at login
• QuotaParserTests.swift: protocol response parsing tests

License

MIT