codex-status-bar

KO | EN

gitlite — search

#csharp #gemini #deep-learning #graphql #android #mcp #kubernetes #self-hosted #css #hacktoberfest

codex-status-bar

(★ 9)

A compact macOS menu bar companion for Codex: live status icons, elapsed timers, active and unread sessions, usage indicators, and approval/input alerts.

File Explorer

ZIP Download

- codex-status-bar.rb
- build_and_run.sh
- - CodexInstallDetector.swift
  - main.swift
  - StatusBarController.swift
  - StatusIconRenderer.swift
- - CodexBarMenuLayout.swift
  - CodexBarPresentation.swift
  - CodexDesktopConfig.swift
  - CodexStateReader.swift
  - CodexUnreadStateReader.swift
  - DateParsing.swift
  - Models.swift
  - RolloutParser.swift
  - StatusLabelMapper.swift
  - UsageFormatter.swift
- - CodexBarMenuLayoutTests.swift
  - CodexBarPresentationTests.swift
  - CodexDesktopConfigTests.swift
  - CodexSessionVisibilityTests.swift
  - CodexStateReaderTests.swift
  - CodexUnreadStateReaderTests.swift
  - DateParsingTests.swift
  - RolloutParserTests.swift
  - StatusLabelMapperTests.swift
  - UsageFormatterTests.swift
.gitattributes
.gitignore
AGENTS.md
build.sh
BUILD_NUMBER
CHANGELOG.md
CONTRIBUTING.MD
LICENSE
Package.swift
README.md
VERSION

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

A compact native macOS menu bar app that shows what Codex is doing locally.

No window or dock icon. No network calls.

## What It Shows

- **Thinking / working** - an animated status icon with an optional live timer.
- **Running a tool** - compact labels such as `Editing`, `Reading`, `Running command`, or `Web 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 12s` or `2 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.

## Requirements

- macOS 13+
- Codex Desktop, the Codex CLI, or a Codex IDE extension.

## Install

### Homebrew

Recommended for developers. Homebrew builds Codex Status Bar from source and launches the app from Homebrew's install location.

```bash
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-bar
```

To update this canary install:

```bash
brew update
brew reinstall codex-status-bar
```

### DMG

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:

```bash
xattr -dr com.apple.quarantine /Applications/CodexStatusBar.app
open /Applications/CodexStatusBar.app
```

You 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](https://support.apple.com/en-us/102445).

### Uninstall

Turn off `Options` > `Start at login` before uninstalling.

For Homebrew:

```bash
brew uninstall codex-status-bar
```

For DMG installs, remove `/Applications/CodexStatusBar.app`.

Removing the app does not remove saved display options. To remove local Codex Status Bar settings too:

```bash
defaults delete io.github.yuriipalam.codexstatusbar 2>/dev/null || true
rm -f ~/Library/Preferences/io.github.yuriipalam.codexstatusbar.plist
```

If the app was removed before Start at login was turned off, remove the stale item from System Settings > General > Login Items & Extensions.

## How It Works

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.

## Privacy

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](CONTRIBUTING.MD). Release notes live in [CHANGELOG.md](CHANGELOG.md).

## Acknowledgements

Thanks to [m1ckc3s](https://github.com/m1ckc3s) and his [Claude Status Bar](https://github.com/m1ckc3s/claude-status-bar) project. The original idea started there for Claude, this app is a Codex-focused take inspired by that work.

## Trademark / Not Affiliated

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.

## License

MIT

codex-status-bar

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README