As of , checked against the official docs.
There are three ways to know when Claude Code has finished or is waiting for you: turn on the terminal’s own notification or bell, add a one-line Notification hook to ~/.claude/settings.json that raises a macOS notification or a Windows dialog box, or use a desktop app that shows each session’s state on screen. With one session a hook is enough; with several, it helps to see which one is waiting.
What does Claude Code notify you about by default?
Claude Code sends a notification when it finishes a task or pauses at a permission prompt and you appear to be away from the terminal. What you get depends on the terminal (official docs, as of November 2026).
- Ghostty, Kitty and iTerm2: a desktop notification. iTerm2 shows it only after you turn on its alert settings.
- Apple Terminal: no sound.
- Other terminals: nothing by default.
To have Claude Code send the bell character in any terminal, add this to ~/.claude/settings.json. Whether the bell makes a sound is your terminal's setting.
{
"preferredNotifChannel": "terminal_bell"
}
How do you get notified with a hook when a session is done or waiting?
Add a Notification hook to ~/.claude/settings.json, and Claude Code runs your command whenever it waits for input or permission. These are the official docs' examples as they stand.
macOS (a notification in Notification Center)
{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
}
]
}
]
}
}
Windows (a dialog box from PowerShell)
{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
}
]
}
]
}
}
A few things to know.
- An empty
matcherfires on every notification. Set it topermission_promptto fire only when a permission prompt has waited about six seconds, or toidle_promptto fire only when Claude finished responding about 60 seconds ago and you haven't typed since. - On macOS,
osascriptnotifications go through the Script Editor app. If nothing appears, runosascript -e 'display notification "test"'once in a terminal, then allow notifications for Script Editor under System Settings > Notifications. - The Windows example opens a dialog box, not a notification in the corner of the screen, so it can open behind your terminal window. Inside WSL,
powershell.exemust be on your PATH.
To know the moment each response ends, put a command of the same shape under the Stop event. This one plays a sound on macOS.
{
"hooks": {
"Stop": [
{
"hooks": [{ "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" }]
}
]
}
}
Hooks run alongside the built-in notification, not in place of it. For one project only, put the hook in that project's .claude/settings.json. The hooks guide has the rest.
Can Codex and Gemini CLI notify you too?
Yes, each has its own settings (as of November 2026).
- Codex: in
~/.codex/config.toml,tui.notificationsturns on notifications from the terminal UI and can be limited to event types such asagent-turn-completeandapproval-requested;tui.notification_methodisauto,osc9orbel. To run an outside program, writenotify = ["python3", "/path/to/notify.py"]; the only event it supports today isagent-turn-complete(Codex configuration docs). - Gemini CLI: turn on
general.enableNotifications(off by default) for terminal notifications on prompts that need you and on session completion;general.notificationMethodisauto,osc9,osc777orbell(Gemini CLI configuration docs).
Which of the three ways fits you?
| Way | Windows | macOS | What it tells you | What it doesn't do |
|---|---|---|---|---|
| The terminal's own notification or bell | Nothing by default; the bell by a setting | A desktop notification in Ghostty, Kitty and iTerm2 | Task finished, waiting on a permission | Other terminals need the bell setting or a hook |
| Notification and Stop hooks | A PowerShell dialog box | A Notification Center alert, a sound | Waiting on approval, waiting for input, response finished | The examples above don't say which session |
| Devalley (a desktop app) | Residents walking along the bottom of the screen | Walking residents, the notch | For each session: working, waiting for you or done, and which project | Sounds, system notifications, phone notifications |
If you run one session and step away, one hook is enough. If you want a sound or Notification Center, hooks are the way.
With several sessions, the question becomes which one is waiting. In Devalley each session is a pixel resident walking along the bottom of your screen; when it has a question or needs approval it hurries to the middle of the screen and hops with a "?" or "May I?" bubble until you answer, and when its turn is done it cheers "Done!". Its name and project stand under its feet, so you see which session it is, and on a Mac it also shows beside the notch at the top of the screen. Codex and Gemini CLI sessions become residents as well as Claude Code's. It is free on Windows and macOS.
What Devalley doesn't do is just as plain: it doesn't tell you of an agent's state by sound, through the system's notification center or on your phone. For the times you aren't looking at the screen, use the hooks or the built-in notification above alongside it.
Frequently asked questions
Which file do Claude Code notification settings go in?
In ~/.claude/settings.json for all your projects, or in a project’s .claude/settings.json for that project only.
Can you get a Claude Code done notification on Windows?
Yes. Put the official PowerShell example in a Notification hook and a dialog box opens. It is a dialog, not a corner notification, so it can open behind the terminal window.
What if the hook is in place on macOS and no notification appears?
osascript notifications go through the Script Editor app. Run osascript -e 'display notification "test"' once in a terminal, then allow notifications for Script Editor under System Settings > Notifications.
How do you set up a Codex done notification?
Turn on tui.notifications in ~/.codex/config.toml, or name a program to run under notify. The event notify supports today is agent-turn-complete.
Can you tell which of several sessions is waiting?
The official hook examples show the same words every time. To tell sessions apart, use Claude Code’s agent view (claude agents) or an app such as Devalley, which shows each session as a resident with its name and project.