Gemini CLI notifications: get a sound or alert when it finishes or needs you

Gemini CLI happily sits at “Waiting for confirmation” while you read something else. It can tell you. The setting is just off by default, and on Windows it behaves differently than the docs suggest.

Before you start: which Gemini CLI you have

A banner on Gemini CLI’s documentation says that for unpaid-tier and Google One users, Gemini CLI was replaced by Antigravity CLI on June 18, 2026. Everything below is about Gemini CLI itself (the gemini command and ~/.gemini/settings.json). If you moved to Antigravity, its settings live elsewhere.

People have wanted this for a long time. The feature request for audio notifications in the Gemini CLI repository (#4310) collected 74 thumbs-up, and a maintainer raised its priority “to reflect how many people care”. A later discussion (#13313) put it simply: “I can never tell when it is done.”

Turn on the built-in notifications

Gemini CLI has an experimental notification feature. It is disabled by default. Turn it on in the CLI with /settings → General → Enable Notifications, or in your settings file:

Once it is on, Gemini CLI alerts you for two events:

• Action required: the model is waiting for your input or for tool approval.
• Session complete: a session finished successfully.

The notification titles are “Gemini CLI needs your attention” and “Gemini CLI session complete”. Gemini CLI does not play a sound of its own: it sends your terminal an escape sequence, and the terminal decides what happens.

How the notification reaches you (and why Windows is different)

A second setting, general.notificationMethod, picks how the alert is sent. The values are auto (default), osc9, osc777 and bell.

The notifications page says the CLI uses the OSC 9 escape sequence and falls back to a terminal bell. The source code is more specific. In auto mode (packages/cli/src/utils/terminalNotifications.ts):

So on Windows Terminal you get the bell, not a toast. What the bell does is a Windows Terminal setting: bellStyle accepts all, audible, window, taskbar and none, and the default is audible. With all, Windows Terminal plays a sound and flashes the taskbar icon; you can pick the sound with bellSound.

If you want to try a real desktop notification instead of the bell, force the method:

Inside tmux or screen, Gemini CLI wraps the sequence in a passthrough escape so it still reaches the outer terminal.

Your own sound with hooks

If you want a specific sound, a popup, or a message to your phone, use hooks. Gemini CLI runs hook commands at fixed points and waits for them to finish. Two events matter here:

• Notification fires when the CLI emits a system alert. Today the only type is ToolPermission (a tool is waiting for your approval). The hook cannot approve or block anything; it is advisory.
• AfterAgent fires once per turn, after the model’s final response. Gemini’s own best-practices page recommends it when “you only need to check the final completion”.

Hooks are on by default (hooksConfig.enabled). A hook prints exactly one JSON object to stdout and nothing else ({} is fine when you have nothing to say). Exit code 0 means success; 2 blocks (and only matters for blocking events); anything else is a warning and the CLI carries on. The default timeout is 60 seconds (timeout is in milliseconds).

Windows (PowerShell)

On Windows, Gemini CLI runs hook commands with pwsh -NoProfile -Command, or powershell.exe if PowerShell 7 is not installed. Save this script as %USERPROFILE%\.gemini\hooks\ding.ps1:

Then point both events at it:

-ExecutionPolicy Bypass avoids the most common failure: PowerShell refusing to run scripts. The Gemini docs suggest Set-ExecutionPolicy RemoteSigned -Scope CurrentUser as the permanent fix.

macOS and Linux

On other systems hooks run with bash -c. A one-line script does the job:

Make it executable (chmod +x ~/.gemini/hooks/ding.sh) and use "command": "$HOME/.gemini/hooks/ding.sh" in the same two events.

Want two different sounds, one for “needs approval” and one for “done”? Make two scripts. A hook can also read the event from stdin: the Notification input carries notification_type, message and details, so you can show the actual request in your popup.

Why your hook doesn’t run

1. Check /hooks panel. It lists every hook Gemini CLI loaded. /hooks enable-all turns them back on if they were disabled.
2. Untrusted folder. In an untrusted folder Gemini CLI ignores the project’s .gemini/settings.json, so project hooks don’t load. Put notification hooks in your user settings (~/.gemini/settings.json) so they work everywhere.
3. Changed hooks count as new. Gemini CLI fingerprints project hooks; if a hook’s name or command changes, it is treated as a new, untrusted hook.
4. Something else on stdout. A stray echo or a PowerShell warning in front of the JSON breaks parsing. Send logs to stderr.
5. Matchers. For Notification and AfterAgent, use "*" (or an empty string) to match everything. Lifecycle events use exact-string matchers, tool events use regular expressions.

Or get asked less often

Notifications help you answer faster; you can also reduce how often Gemini CLI needs you. general.defaultApprovalMode can be default (ask), auto_edit (edits are approved, everything else asks) or plan (read-only). Shift+Tab cycles through them. tools.allowed lists tools that skip the confirmation dialog (for example run_shell_command(git)), and tools.confirmationRequired lists tools that must always ask.

YOLO mode (--yolo, or Ctrl+Y) approves everything and turns on the sandbox by default. It can only be enabled from the command line, and security.disableYoloMode turns it off for good if you share the machine.

Where Pet Island fits

A beep tells you something happened; it doesn’t tell you which terminal, or what Gemini wants to run. Pet Island puts Gemini CLI on a small island at the top of your screen next to your other agents: you see when it is working, when it is waiting for your confirmation and when it is done, with one click to jump to the right terminal.

With Gemini CLI, the confirmation itself still happens in Gemini. Pet Island shows the request and takes you there, but it does not approve Gemini’s tools for you. (Claude Code and Codex requests, by contrast, can be answered right on the island.)

FAQ

Sources

Every setting and behavior on this page was checked against these pages on October 26, 2026. Agents change fast; if something no longer matches, the official page wins.

• Gemini CLI docs: Notifications (experimental)
• Gemini CLI docs: Hooks
• Gemini CLI docs: Hooks reference
• Gemini CLI docs: Writing hooks (PowerShell example)
• Gemini CLI docs: Configuration reference
• Gemini CLI docs: Trusted folders
• Gemini CLI source: terminalNotifications.ts
• Gemini CLI issue #4310: Audio notifications
• Gemini CLI discussion #13313: Enable sound when Gemini is done
• Microsoft Learn: Windows Terminal profile settings (bellStyle, bellSound)
• Microsoft Learn: Console.Beep

KEEP READING