terminal-notifier for Claude Code and Codex.

(1)Install

Install terminal-notifier and send a test banner.

terminal-notifier runs on macOS 10.14 or later. Version 3.1.0 shipped on August 30, 2026, after a long gap since 2.0.0 in 2017, so the project is maintained again. Homebrew is the easy path. The prebuilt release is not notarized, so a downloaded copy needs its quarantine flag removed before macOS will run it.

The first banner triggers a macOS permission prompt. Click Allow, or nothing that follows will show.

brew install terminal-notifier
terminal-notifier -title 'Claude Code' -message 'Test banner' -sound default

(2)Claude Code

Add it to Claude Code’s Stop and Notification hooks.

Stop fires when Claude finishes a turn. Notification fires when Claude needs a permission or is waiting on you. Put both in ~/.claude/settings.json. The -group flag replaces the previous banner from the same group, so a long session does not stack up dozens of them.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "terminal-notifier -title 'Claude Code' -message 'Finished' -sound default -group claude-code" }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          { "type": "command", "command": "terminal-notifier -title 'Claude Code' -message 'Needs you' -sound Funk -group claude-code" }
        ]
      }
    ]
  }
}

(3)Codex

Point Codex’s notify command at it.

Codex runs the notify command from ~/.codex/config.toml with one JSON argument. Its only event today is agent-turn-complete, so this tells you a turn ended, not that Codex needs approval. For approvals, Codex hooks in ~/.codex/hooks.json include a PermissionRequest event you can attach the same command to.

# Codex appends a JSON argument; bash -c ignores it here.
notify = ["bash", "-c", "terminal-notifier -title Codex -message 'Turn complete' -sound default -group codex", "_"]

(4)Troubleshooting

When the banner never appears.

The terminal-notifier README lists the usual causes. Work down the list before reinstalling anything.

• The notification permission was never granted, or a macOS upgrade reset it.
• Focus mode is on and terminal-notifier is not allowed through.
• Scheduled Summary is holding notifications for later.
• Notification Center itself crashed. killall NotificationCenter restarts it.
• There is no GUI session, for example over SSH or from a root launchd job.

terminal-notifier -diagnose
tccutil reset UserNotification fr.julienxx.oss.terminal-notifier
killall NotificationCenter

(5)The ceiling

A banner says that something happened, not what.

With one session, “Claude Code finished” is all you need. With three, you get three identical banners and still have to open each terminal to learn which one is done, which one failed and which one is asking a question. A banner you miss while you are away from the screen is just gone.

You can push it further by putting the project folder in the title, which needs a small script to read cwd from the hook input. Past that, you are rebuilding a status board or a voice layer by hand.

(6)Where Heard fits

Heard tells you what changed, out loud.

Heard installs its own Claude Code and Codex hooks and turns the events into one or two spoken sentences: which project, what changed and whether it needs you. Routine work from parallel sessions is batched into short summaries, while questions and failures come through right away. It runs on macOS 14 or later. The open-source engine is free with local Kokoro voices; the app adds managed voices, Parrot recaps and voice replies.

You do not have to choose: a terminal-notifier banner for “done” and Heard for the content work fine side by side.