A compact native macOS menu bar app that shows what Codex is doing locally.
No window or dock icon. No network calls.
- Thinking / working - an animated status icon with an optional live timer.
- Running a tool - compact labels such as
Editing,Reading,Running command, orWeb search. - Waiting for input or approval - paused status when Codex needs a reply or permission.
- Multiple agents - compact counts such as
2 agents running 4m 12sor2 waiting 1m 0s, timed from the newest active agent. - Unread sessions - a blue-dot status for unread finished Codex sessions, and local usage indicators.
- Idle / done - local usage indicators.
The menu includes active and unread sessions, APP / CLI / IDE badges, usage reset details, an Options submenu for toggles, color and animation controls, and the app version.
- macOS 13+
- Codex Desktop, the Codex CLI, or a Codex IDE extension.
Recommended for developers. Homebrew builds Codex Status Bar from source and launches the app from Homebrew's install location.
brew tap yuriipalam/codex-status-bar https://github.com/yuriipalam/codex-status-bar
brew trust --formula yuriipalam/codex-status-bar/codex-status-bar
brew install codex-status-bar
codex-status-barTo update this canary install:
brew update
brew reinstall codex-status-bar
Download the latest DMG, open it, then drag CodexStatusBar.app into Applications.
The DMG is not Developer ID signed or notarized yet. If macOS blocks the first launch, keep the app and remove the downloaded-app quarantine:
xattr -dr com.apple.quarantine /Applications/CodexStatusBar.app
open /Applications/CodexStatusBar.appYou can also use Apple's UI override: try opening the app once, then open System Settings > Privacy & Security and click Open Anyway. Apple documents that flow in Safely open apps on your Mac.
Turn off Options > Start at login before uninstalling.
For Homebrew:
brew uninstall codex-status-barFor DMG installs, remove /Applications/CodexStatusBar.app.
Removing the app does not remove saved display options. To remove local Codex Status Bar settings too:
defaults delete io.github.yuriipalam.codexstatusbar 2>/dev/null || true
rm -f ~/Library/Preferences/io.github.yuriipalam.codexstatusbar.plistIf the app was removed before Start at login was turned off, remove the stale item from System Settings > General > Login Items & Extensions.
Codex Status Bar resolves CODEX_HOME, falls back to ~/.codex, and polls local Codex session JSONL plus Codex's unread-thread state every 0.2 seconds. It derives status, elapsed time, tool labels, unread sessions, and usage snapshots from local files only.
Those Codex files are implementation details, not a stable public API. If Codex changes its local file format, Codex Status Bar may need an update.
Codex Status Bar reads local Codex activity files and processes them on your Mac. It does not display prompts, responses, command output, or generated thread summaries, and it does not upload telemetry, call OpenAI APIs, install hooks, or modify session logs.
Codex Status Bar stores local display options in macOS preferences and registers itself as a login item on first launch; you can turn Start at login off from Options. The only write to Codex config is user-approved: on first launch, Codex Status Bar can disable Codex Desktop's own duplicate menu bar icon by writing [desktop] mac-menu-bar-enabled = false to $CODEX_HOME/config.toml.
Development, source builds, and packaging live in CONTRIBUTING.MD. Release notes live in CHANGELOG.md.
Thanks to m1ckc3s and his Claude Status Bar project. The original idea started there for Claude, this app is a Codex-focused take inspired by that work.
This is an unofficial open-source side project. It is not affiliated with, endorsed by, or sponsored by OpenAI.
Codex and OpenAI are trademarks of OpenAI. The app includes Codex icon assets for local menu-bar display. The MIT license covers this project's source code only and does not grant rights to OpenAI names, trademarks, or brand assets.
MIT