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

# How to get notified when Claude Code or Codex finishes

Updated 6 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.

There are free ways to get one in both tools. This guide covers them first, then Clacky’s Agent Alerts, which sets the same thing up for you.

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.
-   Don’t want to edit config files? Clacky’s **Agent Alerts** adds the hooks for you and plays a different sound for “done” and “needs you”.

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.  [Clacky’s Agent Alerts: the same, without the config](#clacky-s-agent-alerts-the-same-without-the-config)
6.  [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 · glow

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.

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

Clacky does this in two clicks

Agent Alerts adds the hooks for you, plays a different sound for “done” and “needs you”, stays quiet while you’re in the terminal or on a call, and can keep your Mac awake until the agent finishes. Free for 7 days, no card.

[Try free, 7 daysTry free, 7 days](https://clacky.app/try/)

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

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

### Does Clacky read my code or my prompts?

No. The hook passes Clacky only which tool it was, which terminal app, the session id and what happened (working, done or needs you). It doesn’t pass your prompts, code or output. Nothing is sent anywhere: it’s a line written to a file on your Mac.

### Does it work with Cursor?

Not in Clacky yet: Cursor’s hooks are still in beta. Claude Code and the Codex CLI are supported.

## 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/)
-   [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 small Mac menu-bar app with sounds, a recorder, screenshots, Mac health and agent alerts in one dashboard. [See every tool](https://clacky.app/) · [Try it free for 7 days](https://clacky.app/try/)

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