Ambient › Guides

How to get notified when Gemini CLI finishes or needs you on Mac

Updated September 27, 2026 · 4 min read

Turn on Gemini CLI's own notifications by setting general.enableNotifications to true in ~/.gemini/settings.json. It's experimental, and it alerts you when a task needs approval or finishes: a desktop notification in iTerm2, WezTerm, Ghostty and Kitty, the terminal bell elsewhere. For custom alerts, use AfterAgent and Notification hooks. For a live status, use Ambient.

Which option should you use?

Option 1: Gemini CLI's built-in notifications

// ~/.gemini/settings.json
{
  "general": {
    "enableNotifications": true
  }
}

Gemini CLI then notifies you when an action needs your approval and when a session's task completes. It uses the OSC 9 escape sequence, which iTerm2, WezTerm, Ghostty and Kitty show as a desktop notification. Other terminals get the bell. The feature is experimental, so you may need to turn it on under /settings. Inside tmux, add set -g allow-passthrough on to ~/.tmux.conf.

Option 2: AfterAgent and Notification hooks

Gemini CLI runs hooks at points in its lifecycle. Two matter here: AfterAgent fires when the agent loop ends, and Notification fires when Gemini raises a system notification, such as a request to approve a tool.

// ~/.gemini/settings.json
{
  "hooks": {
    "AfterAgent": [
      {
        "hooks": [
          {
            "name": "done-alert",
            "type": "command",
            "command": "osascript -e 'display notification \"Gemini finished\" with title \"Gemini CLI\"' >/dev/null 2>&1",
            "timeout": 5000
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "name": "needs-you-alert",
            "type": "command",
            "command": "osascript -e 'display notification \"Gemini needs you\" with title \"Gemini CLI\"' >/dev/null 2>&1",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

• Keep stdout clean. Gemini CLI reads a hook's stdout as JSON, so a hook must not print plain text there. That's why the commands above send their output to /dev/null.
• Keep hooks fast. Gemini hooks run synchronously and timeout is in milliseconds.
• Allow Script Editor. osascript notifications belong to Script Editor. Turn on its notifications in System Settings › Notifications, and expect a click to open Script Editor rather than your terminal.

Option 3: Ambient, a live status at the notch

Ambient is a free Mac app that turns Gemini CLI's hooks into a status you can read at a glance: a blue orb while Gemini works, an amber pulse when it needs you, a check when it's done, red when a turn fails. A click returns you to the exact Terminal or iTerm2 tab or tmux pane.

1. Download Ambient from yaml.cafe and drag it to Applications.
2. Open it and click Connect All.
3. Restart Gemini CLI sessions that were already open.

Connecting backs up ~/.gemini/settings.json, then adds hooks named ambient for eight Gemini events, including BeforeAgent, BeforeTool, Notification and AfterAgent. Each finishes in about 15 ms and sends a few short fields over a Unix socket on your Mac. Nothing leaves the machine, and ambient uninstall removes only Ambient's entries.

Common questions

Why doesn't enableNotifications do anything?

The feature is experimental and may need enabling under /settings. It needs a terminal that supports OSC 9, such as iTerm2, WezTerm, Ghostty or Kitty; elsewhere you get only the terminal bell. Inside tmux, add set -g allow-passthrough on to ~/.tmux.conf, and check that your terminal may post notifications in System Settings.

Why does my Gemini CLI hook break the session?

Gemini CLI reads a hook's stdout as JSON, so a hook must not print plain text there. Send any output to stderr or /dev/null. Hooks also run synchronously, so keep them fast and set a timeout in milliseconds.

Can I see Gemini CLI and Claude Code sessions in one place?

Yes. Ambient shows every Gemini CLI, Claude Code and Codex session together at the notch, in the menu bar and on the Dock, with the most urgent state first.

Sources

• Notifications (experimental), Gemini CLI docs
• Gemini CLI hooks, Gemini CLI docs
• Tailor Gemini CLI to your workflow with hooks, Google Developers Blog

More guides: Claude Code notifications on Mac · Codex notifications on Mac