Skip to content
HeardTry for free

Compare · terminal-notifier · 6 min read

terminal-notifier for Claude Code and Codex.

terminal-notifier is a simple, free way to get a macOS banner when a coding agent finishes or needs you. Here is the setup for both agents, a script that puts the project name on each banner, the fixes for banners that never show up, and an optional speech step.

terminal-notifier 3.1.0 · Claude Code and Codex · Checked October 8, 2026

Updated

The short answer

Call terminal-notifier from a Claude Code hook or the Codex notify command. To hear what finished, add Heard (heard.dev).

terminal-notifier is a free, open-source macOS command that posts a Notification Center banner; Heard (heard.dev), the voice context layer for agents, can run next to it and say what Claude Code or Codex finished or needs from you. Install terminal-notifier with brew install terminal-notifier, then run it from Claude Code’s Stop and Notification hooks and from Codex’s notify setting. If the banner never appears, run terminal-notifier -diagnose: the usual causes are a missing permission, Focus mode or Scheduled Summary. For Heard, build its free open-source engine from github.com/heardlabs/heard, then heard install claude-code or heard install codex adds Heard’s hooks and leaves your terminal-notifier setup in place.

With several sessions, put the project name in each banner: both agents pass the working folder (cwd) in their event JSON, and a short script turns it into the title. For a free spoken line without Heard, add macOS say to the same hook. Heard goes further and says what changed and which session needs you.

Side by side

terminal-notifier next to the other ways to get pinged.

Facts from each project’s own README and site. Checked October 8, 2026.

ToolWhat you getAfter you miss itSeveral sessionsPrice
terminal-notifierbrew · macOS 10.14+A banner with your title and messageNotification Center history onlySame-looking banners unless you put the project in the titleFree, open source
Sound hookafplayA chime per eventNothingEvery session sounds the sameFree, built in
AgentNotchnotch appA visual board of sessions, approvals and usageThe board still shows who needs youGrouped by project$9.99 one-time, 14-day trial
Heardvoice layerA spoken sentence: what changed and what needs youAsk Parrot what changed while you were away (Heard Power)In the app, each update starts with the project nameFree engine; paid app plans

AgentNotch price and trial from its own site.

(1)Install

Install terminal-notifier and send a test banner.

terminal-notifier runs on macOS 10.14 or later. Version 3.0.0 shipped on August 23, 2026, after a long gap since 2.0.0 in 2017, and 3.1.0 followed on August 30, 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.

Terminal · install and test
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.

Always pass -message. Without it, terminal-notifier uses piped input as the body, and a hook pipes its event JSON in.

~/.claude/settings.json
{
  "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/config.toml
# 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)Project name

Put the project name on every banner.

Claude Code hooks get the event as JSON on stdin, and Codex notify gets it as an extra argument. Both include cwd, the folder the agent is working in. The script below turns that folder name into the banner title, puts the agent in the subtitle and groups by agent and project, so each agent and project keeps only its latest banner.

For Claude Code’s Notification event it shows Claude’s own notification text instead of a fixed message (the hooks reference example is “Claude needs your permission”). It needs jq (brew install jq). Point the hooks at the script instead of calling terminal-notifier directly.

~/.local/bin/agent-banner
#!/bin/bash
# Usage: agent-banner AGENT MESSAGE
# Claude Code pipes the event JSON on stdin; Codex notify adds it as one more argument.
agent="$1"
json="${3:-$(cat)}"
dir=$(printf '%s' "$json" | jq -r '.cwd // empty')
project="${dir##*/}"
message=$(printf '%s' "$json" | jq -r --arg m "$2" '.message // $m')
terminal-notifier -title "${project:-$agent}" -subtitle "$agent" -message "$message" \
  -group "$agent-$project" -sound default
Terminal · make it executable and test it
chmod +x ~/.local/bin/agent-banner
echo '{"cwd":"/Users/you/code/api"}' | ~/.local/bin/agent-banner 'Claude Code' 'Finished'
Hook commands and Codex notify
# ~/.claude/settings.json: use these as the Stop and Notification commands
~/.local/bin/agent-banner 'Claude Code' 'Finished'
~/.local/bin/agent-banner 'Claude Code' 'Needs you'

# ~/.codex/config.toml: use the full path to the script
notify = ["/Users/you/.local/bin/agent-banner", "Codex", "Turn complete"]

(5)Optional

Add speech if a banner is not enough.

terminal-notifier has no speech option: -sound plays a system sound. The quickest way to hear something is a second hook command that runs macOS say, for example say "Claude finished" next to the banner in the Stop hook. It says the same words every time.

Heard goes further. It turns agent events into one or two spoken sentences about what changed and whether a session needs you. In the Heard app, updates from parallel sessions start with the project name (set your own with label: in a repo’s .heard.yaml), while questions and failures come through right away. Its hook installer adds Heard’s own entry and leaves your terminal-notifier hook in place, and Claude Code runs all matching hooks in parallel, so you keep the banner. For Codex it writes ~/.codex/hooks.json and does not touch notify. Heard runs on macOS 14 or later, and the open-source engine is free with local Kokoro voices.

(6)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 · diagnose and reset
terminal-notifier -diagnose
tccutil reset UserNotification fr.julienxx.oss.terminal-notifier
killall NotificationCenter

(7)The ceiling

A banner says that something happened, not what.

With one session, “Claude Code finished” is all you need. With three, the project-name script tells you which one stopped and, for a Claude Code Notification, Claude’s one-line reason. It does not tell you what the session did or whether the work failed, so you still open the terminal to find out. A banner you miss while you are away from the screen leaves only a line in Notification Center.

Past that point you want a status board you glance at, such as AgentNotch, which groups sessions by project and shows pending approvals, or a voice that tells you, such as Heard.

A few more details

Questions?

Does terminal-notifier work with Claude Code?

Yes. Call it from the Stop hook for “finished” and the Notification hook for “needs you” in ~/.claude/settings.json. Claude Code’s file watcher normally picks up hook edits without a restart. Always pass -message, because without it terminal-notifier uses the hook’s piped JSON as the body.

How do I show the project name in a terminal-notifier banner?

Read cwd from the event JSON (stdin for Claude Code hooks, the extra argument for Codex notify) and pass the folder name as -title. The script on this page does that and keeps one banner per agent and project with -group.

Can terminal-notifier read the message aloud?

No. It posts a banner and can play a system sound with -sound. For speech, run macOS say from the same hook, or use a voice layer such as Heard, which speaks what changed in each session.

Why do my terminal-notifier banners not show up?

Run terminal-notifier -diagnose. The usual causes are a missing or reset notification permission, Focus mode, Scheduled Summary, a crashed Notification Center, or running without a GUI session such as over SSH.

Can terminal-notifier tell me when Codex needs approval?

Not through notify, which only fires on agent-turn-complete. Attach it to the PermissionRequest event in Codex hooks instead.

Does Heard replace terminal-notifier?

You do not have to choose. terminal-notifier is the right tool for a single run you are waiting on, and it keeps working when Heard is installed: Heard’s hook installer adds its own entry and leaves yours in place. Heard is for when you run several sessions or step away from the screen and want to hear what happened without opening each terminal.

Keep going

Give your agents a voice.

Keep the context. Get on with your work.

Download for Mac

Includes 14 days of free Heard. No card needed.