How to get notified when Claude Code or Codex finishes

How agents tell you they’re done

Both tools can run a command of yours at the right moment. That’s all a notification is: Claude Code calls it a hook, Codex calls it notify. Whatever the command does (play a sound, show a banner, flash the screen) happens when the agent stops or asks for input.

Claude Code: the built-in notification

When Claude Code finishes, or waits on a permission prompt, it can send a desktop notification by itself. Anthropic’s docs say this works out of the box in Ghostty and Kitty. In iTerm2, turn it on once:

1. iTerm2 → Settings → Profiles → Terminal.
2. Check Notification Center Alerts.
3. Click Filter Alerts and enable Send escape sequence-generated alerts.

Running Claude Code inside tmux? Add set -g allow-passthrough on to ~/.tmux.conf, or the notification never reaches your terminal. You can also pick how Claude Code notifies you (for example a terminal bell) in its /config settings.

Source: Claude Code docs: terminal setup

Claude Code: a hook that plays a sound

In Apple’s Terminal, VS Code or any other terminal, a hook does it. Hooks live in ~/.claude/settings.json (for every project) or .claude/settings.json (one project). Two events matter:

• Stop: Claude finished its answer.
• Notification: Claude needs you (a permission prompt, or it’s been waiting for input).

This plays a macOS sound for both. Merge it into your settings file (keep anything already in it):

{
  "hooks": {
    "Stop": [{ "hooks": [{ "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" }] }],
    "Notification": [{ "matcher": "", "hooks": [{ "type": "command", "command": "afplay /System/Library/Sounds/Ping.aiff" }] }]
  }
}

Prefer a banner? Use this command instead (the same as Anthropic’s example):

osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'

Type /hooks in Claude Code to see what’s set up. New hooks apply to sessions you start after saving. The sounds in /System/Library/Sounds/ are free to use: Glass, Ping, Pop, Purr, Submarine and more.

Sources: hooks reference · hooks guide

Codex: the notify setting

The Codex CLI runs a program of yours after every turn, set with notify in ~/.codex/config.toml. Codex adds a JSON description of the turn as the last argument (its type is agent-turn-complete), which a simple sound command can ignore:

notify = ["sh", "-c", "afplay /System/Library/Sounds/Glass.aiff"]

notify is a top-level key: put it above any [section] in the file. Codex also has built-in notifications in its terminal UI (notifications under [tui]) that use the terminal’s own notification or bell; whether you see a banner depends on your terminal.

Codex’s notify fires when a turn completes. It doesn’t have a separate “needs your approval” event the way Claude Code’s Notification hook does.

Source: Codex docs: advanced configuration

Clacky’s Agent Alerts: the same, without the config

If you’d rather not edit JSON and TOML, Clacky (a Mac menu-bar app) has Agent Alerts. It uses the same hooks as above, so nothing watches your screen or reads your terminal:

1. Open Clacky’s dashboard → Agent Alerts.
2. Next to Claude Code or Codex, click Set Up…. Clacky shows the exact lines it will add; click Add Hooks. It keeps a backup of your file next to it (settings.json.clacky-backup).
3. Click Send a Test Alert to hear both sounds.

What you get:

• A different sound for done (a rising chord) and needs you (two taps and a question), with five voices to pick from per agent.
• An optional soft glow around the screen edge for about a second. It’s click-through and never shows in recordings.
• Quiet when it’s in front (silent while the agent’s terminal is the active app) and Quiet during calls (silent while the mic is in use), both on by default.
• A dot per session in the menu bar: working, waiting or done. Click one to bring its terminal forward.
• Keep Awake → Until My Agent Is Done, so a long run doesn’t stop because your Mac went to sleep.

Claude Code works in any terminal and in the Claude app’s Code tab. Codex works with the CLI and gets the done sound (Codex sends no “needs you” event). If your Codex config already has a notify line, Clacky leaves it alone and tells you, instead of replacing it. Remove… takes out only Clacky’s lines.

If nothing happens

• Restart the session. Hooks are read when a session starts, so one that was already running won’t notify.
• Check the file parses. A missing comma in settings.json stops every hook. Paste it into any JSON checker.
• Test the command alone. Run afplay /System/Library/Sounds/Glass.aiff in Terminal. No sound? Check your output device and volume.
• Banners don’t show? Check System Settings → Notifications for your terminal (or Script Editor, for osascript), and Focus modes.
• Two sounds at once? You have two setups (say, your own hook and Clacky’s). Keep one.