[Clacky](https://clacky.app/)/Guides

# 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.

On this page

1.  [How agents tell you they’re done](#how-agents-tell-you-they-re-done)
2.  [Claude Code: the built-in notification](#claude-code-the-built-in-notification)
3.  [Claude Code: a hook that plays a sound](#claude-code-a-hook-that-plays-a-sound)
4.  [Codex: the notify setting](#codex-the-notify-setting)
5.  [If nothing happens](#if-nothing-happens)

## 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](https://code.claude.com/docs/en/terminal-config)

## 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](https://code.claude.com/docs/en/hooks) · [hooks guide](https://code.claude.com/docs/en/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](https://developers.openai.com/codex/config-advanced)

## 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.

## More guides

-   [Keep your Mac awake, lid closedClamshell mode, caffeinate, pmset and apps, and what each one really does.](https://clacky.app/keep-mac-awake-lid-closed/)
-   [Keyboard & click sounds on MacHow they work, the permission they need, the apps, and fixes.](https://clacky.app/mac-keyboard-sounds/)
-   [Show mouse clicks on MacThe built-in option, editors, and a live ripple with a sound.](https://clacky.app/show-mouse-clicks-mac/)
-   [Click sound on MacNo built-in setting: how to add one, and the permission it needs.](https://clacky.app/mac-click-sound/)
-   [Best keyboard sound apps17 free and paid apps side by side, and which one fits you.](https://clacky.app/best-keyboard-sound-apps-mac/)
-   [Keyboard sounds for focusSoft typing sounds for study, writing and coding, in your headphones.](https://clacky.app/keyboard-sounds-for-focus/)
-   [Keyboard sounds explainedWhat thock, creamy, clacky and poppy mean, and how each one sounds.](https://clacky.app/keyboard-sounds-explained/)
-   [Cozy Mac appsIdle games, ambient sounds, pets and soft clicks that run while you work.](https://clacky.app/cozy-mac-apps/)
-   [Best cursor highlighter appsSpotlights, click ripples and click sounds for demos, calls and recordings.](https://clacky.app/best-cursor-highlighter-apps-mac/)
-   [Keyboard sounds not workingInput Monitoring, Secure Input, the output device and quiet settings.](https://clacky.app/keyboard-sounds-not-working-mac/)
-   [Teleprompter on MacRead your script under the camera, and keep it out of the recording.](https://clacky.app/teleprompter-mac/)
-   [Show clicks and record click soundsGet the click ripple and the click sound into any Mac screen recording.](https://clacky.app/record-click-sound/)
-   [Typing test with keyboard soundsA 30-second typing test you can hear, right in your browser.](https://clacky.app/typing-test/)

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](https://clacky.app/) · [Hear the sounds in your browser](https://clacky.app/)

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