codex-autofocus is a small macOS utility that brings the Codex desktop app to
the front when a Codex turn finishes.
It has two parts:
- a command-line helper that Codex runs from a
Stophook - a menu bar app for turning the behavior on or off and repairing the hook setup
The helper is intentionally narrow. It does not read your Codex transcript or control other apps. When autofocus is enabled, it runs:
/usr/bin/open -b com.openai.codexEach hook run also appends a short diagnostic line to:
~/.codex/codex-autofocus/debug.logThe log records timing, hook event metadata, thread and turn ids when Codex provides them, and the result of the focus command. It deliberately avoids writing prompt text or assistant message text.
Pushover notifications are optional. When configured, the helper sends your Pushover application token and user key, the Codex thread title, and a generic task-finished message to Pushover's HTTPS API. Prompt and response content never leave the Mac.
Some Codex internals can also emit Stop hook events. When Codex sends a hook
payload with a null transcript path, codex-autofocus treats it as an internal
or ephemeral turn and skips bringing Codex forward. The skip is written to the
debug log.
- macOS 13 or newer
- Swift 5.9 or newer for building from source
- Codex hooks enabled in Codex
Homebrew is the easiest install path once the tap is available:
brew tap jonasjancarik/tap
brew install codex-autofocus
codex-autofocus install --binary "$(brew --prefix codex-autofocus)/bin/codex-autofocus"Start the menu bar app with:
codex-autofocus-menuHomebrew formula apps do not always show up in Spotlight because the app bundle
lives under Homebrew's install prefix. To make Codex Autofocus available from
Spotlight, create a user Applications shortcut:
codex-autofocus install-app --app "$(brew --prefix codex-autofocus)/Codex Autofocus.app"To start the menu bar app automatically, turn on Open at Login from the app
menu or run:
codex-autofocus enable-login-item --app "$(brew --prefix codex-autofocus)/Codex Autofocus.app"This creates a per-user LaunchAgent. It starts the app when you log in to macOS, which is the practical version of "start on boot" for a menu bar app.
The first command installs the helper and menu app. The codex-autofocus install
command registers the Codex hook. Codex may still ask you to approve that hook
before it runs.
From the project directory:
scripts/install.shThe installer builds the helper and menu app, installs them under ~/.codex,
registers a managed Stop hook, opens the menu app, and sets it to open when
you log in. It also creates a Codex Autofocus shortcut in your user
Applications folder.
The installed hook looks like this:
'/Users/janca/.codex/bin/codex-autofocus' --hook --managed-by codex-autofocusThe --managed-by codex-autofocus marker is important. It lets this project find
and update only its own hook while leaving hooks from other tools alone.
If an older experimental notify = codex-autofocus setup is present, the
installer migrates away from it and restores the previous notifier when it can.
Codex asks you to review new or changed hooks before it runs them. That is a security step: hooks can run outside the sandbox.
After installing, open Codex's hook review UI and trust the Codex Autofocus
Stop hook. The menu bar app shows Approve hook in Codex until Codex has
recorded that trust.
There is also a manual option: Advanced > Trust Installed Hook....
Use it only if you want Codex Autofocus to write the hook approval record directly
to ~/.codex/config.toml instead of approving the hook through Codex's normal
review UI. The app shows a confirmation prompt first, and this is never done
automatically.
script/build_and_run.shThis builds dist/Codex Autofocus.app and launches it as a menu-bar-only app.
The app has no Dock icon.
The bundle can also be built without launching it:
script/package_app.sh --configuration releaseThe menu is intentionally small:
- current state, such as
On · Hook installed Turn Autofocus OnorTurn Autofocus OffOpen at LoginorStop Opening at Login- Pushover setup, test, and on/off controls
Advancedrepair and file actionsQuit Codex Autofocus
Status refreshes automatically while the app is running. There is no manual refresh command.
The menu bar app is the easiest way to toggle autofocus.
The command-line helper can do the same thing:
~/.codex/bin/codex-autofocus enable --binary ~/.codex/bin/codex-autofocus
~/.codex/bin/codex-autofocus disable --binary ~/.codex/bin/codex-autofocusEnable and disable only change Codex Autofocus runtime state. They do not edit
~/.codex/hooks.json or ~/.codex/config.toml.
~/.codex/bin/codex-autofocus status --binary ~/.codex/bin/codex-autofocusStatus reports whether autofocus is enabled, whether the managed hook is registered, which hook command is installed, and whether any setup issue needs attention.
Open the menu and choose Pushover Notifications > Set Up Pushover.... Enter
the application token and user key from your Pushover account, then use
Send Test Notification to verify delivery.
Credentials are stored locally at:
~/.codex/codex-autofocus/pushover.jsonThe file is readable only by your macOS user. You can also configure and test Pushover from the command line:
PUSHOVER_APP_TOKEN="..." PUSHOVER_USER_KEY="..." \
~/.codex/bin/codex-autofocus configure-pushover
~/.codex/bin/codex-autofocus test-pushoverPushover remains active if you turn autofocus off; use
Pushover Notifications > Turn Off Pushover when you do not want remote
notifications.
The helper resolves the title by matching the hook's session id in
~/.codex/session_index.jsonl. If Codex has not indexed the title yet, the
notification falls back to Codex task finished.
scripts/uninstall.shThis removes only hooks marked --managed-by codex-autofocus from
~/.codex/hooks.json. It does not remove unrelated hooks.
Useful commands:
swift build
swift test
swift run codex-autofocus --help
scripts/smoke.shscripts/smoke.sh removes and re-registers the managed hook, verifies that the
legacy notify setup is not active, toggles autofocus off and on, and runs dummy
hook invocations. It leaves the hook registered and autofocus enabled.
Project layout:
Sources/CodexAutofocusCore: shared install, hook, status, and trust logicSources/CodexAutofocus: command-line helperSources/CodexAutofocusMenuBar: macOS menu bar appTests/CodexAutofocusCoreTests: regression testsdocs/menu-bar-app.md: notes on the menu bar app behavior
