Codex Notify

Codex Notify is a small local macOS menu bar helper for Codex Desktop. It watches Codex session transcript files and shows a custom in-app toast whenever a new assistant reply arrives while Codex is in the background.

Screenshot

This is what a reply looks like when Codex Notify catches a new assistant message:

What It Does

• Watches for newly appended assistant replies.
• Detects both commentary and final answers.
• Resolves the related thread title.
• Shows a custom floating toast in the top-right corner of the screen.
• Keeps a Recent Replies menu in the menu bar app for the current run.
• Opens Codex when you click a toast or choose the menu action.
• Supports Launch at Login.
• Shows runtime status in the menu if polling fails or the Codex session folder is missing.

Requirements

• macOS 13 or newer.
• Codex Desktop installed on the machine.
• Xcode / Command Line Tools with Swift 6 support.
• A local Codex setup that writes session data into a Codex home directory.

Codex Home Resolution

Codex Notify resolves the Codex data directory in this order:

1. --codex-home /path/to/.codex
2. CODEX_HOME=/path/to/.codex
3. Saved UserDefaults value for codexHomePath
4. Fallback to ~/.codex

If your packaged app needs a persistent custom location, set it with:

defaults write local.codex.notify codexHomePath -string "/path/to/.codex"

Quick Start

Clone the repository and build the app bundle:

./scripts/build-app.sh

Launch it with:

open "dist/Codex Notify.app"

Once running, the app appears as a menu bar accessory app. Open the bell icon to:

• inspect recent replies,
• clear the unread indicator,
• open Codex,
• toggle Launch at Login,
• quit the helper.

Optional Local Install

If you want the built app in your Applications folder:

cp -R "dist/Codex Notify.app" /Applications/
open "/Applications/Codex Notify.app"

If you use Launch at Login, running the packaged .app is the safest option because the launch agent records the current app or executable path.

Development Commands

Build in debug mode:

swift build

Run directly from SwiftPM:

swift run CodexNotify

Run the test suite:

swift test

Build the distributable app bundle:

./scripts/build-app.sh

Important Notes

• Existing transcript history is ignored on startup. Only newly appended replies are treated as new events.
• Recent Replies lives in memory only for the current app session.