<!-- Generated from the same content as https://heard.dev/compare/terminal-notifier-for-coding-agents. -->

# terminal-notifier for Claude Code and Codex: Setup, Fixes and Limits (2026)

Source: https://heard.dev/compare/terminal-notifier-for-coding-agents

Set up terminal-notifier for Claude Code and Codex, put the project name on every banner, fix banners that never appear, and add speech if you want it.

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 November 10, 2026

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](https://github.com/julienXX/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](https://code.claude.com/docs/en/hooks) and from Codex’s [`notify`](https://learn.chatgpt.com/docs/config-file/config-advanced) 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](https://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.

- **terminal-notifier brew · macOS 10.14+:** What you get: A banner with your title and message; After you miss it: Notification Center history only; Several sessions: Same-looking banners unless you put the project in the title; Price: Free, open source
- **Sound hook afplay:** What you get: A chime per event; After you miss it: Nothing; Several sessions: Every session sounds the same; Price: Free, built in
- **AgentNotch notch app:** What you get: A visual board of sessions, approvals and usage; After you miss it: The board still shows who needs you; Several sessions: Grouped by project; Price: $9.99 one-time, 14-day trial
- **Heard voice layer:** What you get: A spoken sentence: what changed and what needs you; After you miss it: Ask Parrot what changed while you were away (Heard Power); Several sessions: In the app, each update starts with the project name; Price: Free 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
```

**Downloaded the release instead?**

Clear the quarantine flag first: `xattr -dr com.apple.quarantine /path/to/terminal-notifier.app`.

(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](https://learn.chatgpt.com/docs/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](https://code.claude.com/docs/en/hooks#notification) 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"]
```

**The test banner**

It should read “api” as the title and “Claude Code” as the subtitle. Replace `you` in the Codex path with your user name.

(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](https://github.com/heardlabs/heard) 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
```

**Exit code 3**

terminal-notifier exits with code 3 when notifications are not authorized. Grant the permission in System Settings → Notifications.

(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

## Related Heard resources

[**Heard vs. AgentNotch** A status board you glance at, or a voice you hear.](https://heard.dev/compare/heard-vs-agentnotch) [**Spoken notifications for Codex** notify, hooks, Voxlert, agent-notify and Heard.](https://heard.dev/compare/codex-spoken-notifications) [**Get notified when Claude Code needs you** Notification hooks for approvals, questions and idle prompts.](https://heard.dev/guides/claude-code-needs-input-notification) [**All comparisons** Every Heard comparison page in one place.](https://heard.dev/compare)

## Give your agents a voice.

Keep the context. Get on with your work.

[Download for Mac](https://heard.dev/download/use-cases?format=dmg)

Includes 14 days of free Heard. No card needed.
