Codex Usage Menu Bar

Weekly Codex limits and live task activity in your macOS menu bar.

English · 한국어

Codex Usage Menu Bar is a lightweight, native macOS status app for people who keep several Codex tasks running at once. It combines weekly allowance, reset timing, separate main/subagent counts, project context, model, reasoning effort, Fast mode, and cumulative tokens without requiring a separate dashboard.

⠋ 2 (+1)  [Codex icon]  30% · 4일 6시간 후 갱신

Open the menu to inspect each running task:

my-project                         ← project
Improve the onboarding flow       ← Codex task
⚡ Fast · gpt-5.6-sol · 추론 medium · 누적 6.9만 토큰

The app menu is currently Korean. This guide explains the labels in English.

Why use it?

• See the weekly percentage still available, not only the amount already used.
• Know how long remains until reset in days and hours.
• Spot active work from the animated spinner and the compact main (+subagent) count.
• Distinguish projects, parent tasks, and spawned subagents at a glance.
• See each task's current model, reasoning effort, Fast mode, and cumulative token usage.
• Click a task row to open that exact conversation in Codex.
• Redeem an available limit-reset credit after an explicit confirmation.

Feature overview

Area	Behavior
Menu bar	Spinner, compact main (+subagent) count, Codex icon, available percentage, and relative reset time.
Task tree	Primary tasks and spawned subagents appear together in one parent-child hierarchy.
Project context	The workspace project name appears in a smaller line above the task title.
Runtime details	Shows the active model, reasoning effort, ⚡ Fast for the priority service tier, and cumulative input/output tokens.
Conversation links	Any visible task, subagent, or parent row opens its codex://threads/... conversation.
Refresh control	Choose 1, 5, 10, 30, or 60 minutes; the choice persists across launches.
Reset credits	Shows the available count and asks for confirmation before consuming one.
Local-first	Reads local Codex session metadata and reuses the signed-in Codex CLI. No separate backend.

Requirements

• macOS 13 Ventura or later
• Swift 5.9 or later for source builds
• A locally installed and signed-in Codex CLI

If Codex CLI is not installed, follow the current official macOS/Linux installer flow:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Then open a project directory, run codex, and choose Sign in with ChatGPT or another available sign-in method.

codex --version
codex

Install from source

git clone https://github.com/junhoi-pk/codex-usage-menubar.git
cd codex-usage-menubar
./scripts/build-app.sh
open dist/CodexUsageMenuBar.app

The build script:

1. Builds an optimized Swift executable with the SDK selected by xcrun.
2. Creates dist/CodexUsageMenuBar.app.
3. Copies a local Codex icon when one is available.
4. Applies an ad-hoc signature so the app can run locally.

There is no prebuilt release yet.

Verify the rate-limit connection

With the menu app closed, run:

dist/CodexUsageMenuBar.app/Contents/MacOS/CodexUsageMenuBar --print-once

This prints the current allowance summary and exits. Running it while another app-server client is starting may produce a transient connection error; the menu's 지금 새로고침 action can be used instead.

Reading the interface

Menu bar

Display	Meaning
⠋	Animated only while at least one Codex task is active.
2 (+1)	Two main Codex tasks and one spawned subagent are active.
Codex icon	Loaded locally when available; otherwise the macOS terminal symbol is used.
30%	Percentage of the selected weekly allowance still available.
4일 6시간 후 갱신	The allowance resets in 4 days and 6 hours.

Task rows

Every task row uses three lines:

1. Project — derived from the task workspace directory.
2. Task title — the Codex thread name or subagent identity.
3. Runtime metadata — Fast mode, model, reasoning effort, and compact cumulative tokens.

Hover a row to see the exact token total. Large values are shortened with Korean number units such as 만 and 억. The value comes from Codex's cumulative total_token_usage.total_tokens; cached input is already part of the reported input total and is not added a second time.

Start automatically after login

1. Open System Settings → General → Login Items.
2. Under Open at Login, click +.
3. Select dist/CodexUsageMenuBar.app.

Keep the app in the same location afterward. Moving or deleting it breaks the login item.

How it works

flowchart LR
    CLI["Signed-in Codex CLI"] --> RPC["codex app-server"]
    RPC --> Limits["Rate limits and reset credits"]
    Sessions["~/.codex/sessions/*.jsonl"] --> Activity["Lifecycle, hierarchy, model, tokens"]
    Limits --> Menu["macOS menu bar"]
    Activity --> Menu
    Menu --> DeepLink["codex://threads/{id}"]

Loading

• account/rateLimits/read supplies rate-limit windows and reset-credit availability.
• The longest primary Codex window is treated as the weekly allowance.
• Available percentage is calculated as 100 - usedPercent.
• account/rateLimitResetCredit/consume is called only after confirmation.
• Local session logs are checked every two seconds for structured start, completion, abort, hierarchy, model, reasoning-effort, service-tier, and token events.
• Normal completion and turn_aborted both end a task.
• Internal Codex helper sessions are excluded from the user-visible count.
• A session without a terminal event ages out after six hours to prevent stale activity.

The Codex executable is searched in this order:

1. CODEX_CLI_PATH
2. ~/.local/bin/codex
3. /opt/homebrew/bin/codex
4. /usr/local/bin/codex
5. /Applications/Codex.app/Contents/Resources/codex

Privacy and safety

• Authentication files and credentials are not read, copied, or stored directly.
• Session processing happens locally on your Mac.
• The app reads only the session metadata needed for lifecycle, hierarchy, project, model, reasoning effort, service tier, and token totals.
• Prompts and responses are not sent to a project-owned server; this project has no backend.
• Reset-credit consumption always requires explicit confirmation.
• Builds, session data, credentials, and proprietary Codex icon files are excluded from Git.

Troubleshooting

Codex CLI를 찾을 수 없습니다

Confirm that codex --version works in Terminal. For a custom installation path:

CODEX_CLI_PATH=/absolute/path/to/codex open dist/CodexUsageMenuBar.app

Usage information does not appear

Run codex once and confirm that sign-in succeeds, then choose 지금 새로고침 from the menu.

A task count remains after work stops

Normal completion and aborted turns are removed immediately when their structured event is written. A process that exits without either event ages out after six hours.

The icon looks like a terminal

Official Codex artwork is intentionally not committed. If no compatible local icon is found, the app uses the macOS terminal.fill symbol.

The app does not reopen after restarting the Mac

Source builds do not register themselves as login items. Add the built .app manually and keep it at the same path.

Project structure

.
├── Package.swift
├── Resources/
│   └── Info.plist
├── Sources/CodexUsageMenuBar/
│   └── main.swift
└── scripts/
    └── build-app.sh

Compatibility

• The project relies on Codex CLI app-server RPCs and local session-log formats; future Codex releases may require updates.
• Reset credits depend on account eligibility, plan, and service response.
• The menu UI is currently Korean-only.
• Distribution is source-only and locally ad-hoc signed.

Disclaimer

This is an independent, unofficial community project. It is not affiliated with, endorsed by, or maintained by OpenAI. Codex and related marks belong to their respective owners.