MacPipYour next Mac app is here.macpip.com →

How to get notified when Claude Code or Codex finishes

Updated 22 October 2026

You start a long task in Claude Code or Codex, switch to something else, and come back ten minutes later to find it stopped two minutes in, waiting for a yes. A sound or a notification when the agent finishes or needs your OK fixes that.

Both tools can do this for free, built in or with a line or two of config. This guide walks through each way, step by step.

The short version

  • Claude Code can already notify you in Ghostty, Kitty and iTerm2 (iTerm2 needs one setting). In other terminals, add a hook.
  • A Claude Code hook on Stop fires when it finishes; one on Notification fires when it needs you. Point either at afplay for a sound or osascript for a notification.
  • Codex: add a notify line to ~/.codex/config.toml, or turn on its built-in terminal notifications.
  • Nothing happens? Restart the session: hooks are read when a session starts.

How agents tell you they’re done

Claude Code or Codexfinishes, or needs you
Hook / notifyruns your command
You hear itsound · banner · bell
Every method on this page works the same way: the agent runs a command at the right moment.

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.

A nicer Mac while your agent works

Clacky makes the Mac itself feel nicer while agents work: click and keyboard sounds, and a screen recorder when you want to show what the agent built. $4.99 once for 1 Mac.

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

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, a hook in ~/.claude/settings.json and another in the project’s .claude/settings.json). Keep one.

Questions

Does Claude Code have a built-in notification sound?

It can send a desktop notification by itself in Ghostty, Kitty and iTerm2 (iTerm2 needs Send escape sequence-generated alerts turned on). For a sound in any terminal, add a Stop or Notification hook that runs afplay.

What’s the difference between the Stop and Notification hooks?

Stop runs when Claude finishes answering. Notification runs when Claude needs you: a permission prompt, or it has been waiting for your input. Most people want both, with different sounds.

Can Codex tell me when it needs approval?

Codex’s notify program runs when a turn completes (agent-turn-complete). There’s no separate approval event for it today, so you hear it when the turn ends.

Do these alerts work with Claude Code on the web (claude.ai/code in Chrome)?

Not today. Claude Code on the web runs in Anthropic’s cloud, so its hooks run there and never reach your Mac. An afplay or osascript hook only hears sessions that run on your Mac: in a terminal or in the Claude app’s Code tab. To get alerts for a web session, continue it on your Mac with claude --teleport in Terminal, then it alerts like any local session.

New to Clacky? It’s a cozy Mac menu-bar app with click and keyboard sounds, a screen recorder, screenshots and a little harbour town that grows while you work. See every tool · Hear the sounds in your browser

Checked on 22 October 2026. Something changed, or something here is wrong? Email hello@clacky.app.