How to get notified when Claude Code or Codex finishes
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
afplayfor a sound orosascriptfor a notification. - Codex: add a
notifyline 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
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:
- iTerm2 → Settings → Profiles → Terminal.
- Check Notification Center Alerts.
- 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.
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.jsonstops every hook. Paste it into any JSON checker. - Test the command alone. Run
afplay /System/Library/Sounds/Glass.aiffin 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.jsonand 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.
More guides
- Keep your Mac awake, lid closedClamshell mode, caffeinate, pmset and apps, and what each one really does.
- Keyboard & click sounds on MacHow they work, the permission they need, the apps, and fixes.
- Show mouse clicks on MacThe built-in option, editors, and a live ripple with a sound.
- Click sound on MacNo built-in setting: how to add one, and the permission it needs.
- Best keyboard sound apps17 free and paid apps side by side, and which one fits you.
- Keyboard sounds for focusSoft typing sounds for study, writing and coding, in your headphones.
- Keyboard sounds explainedWhat thock, creamy, clacky and poppy mean, and how each one sounds.
- Cozy Mac appsIdle games, ambient sounds, pets and soft clicks that run while you work.
- Best cursor highlighter appsSpotlights, click ripples and click sounds for demos, calls and recordings.
- Keyboard sounds not workingInput Monitoring, Secure Input, the output device and quiet settings.
- Teleprompter on MacRead your script under the camera, and keep it out of the recording.
- Show clicks and record click soundsGet the click ripple and the click sound into any Mac screen recording.
- Typing test with keyboard soundsA 30-second typing test you can hear, right in your browser.
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.