From 97dfbd45981434f979c65dce3253fe1bac4254c7 Mon Sep 17 00:00:00 2001
From: Jenna Inouye <jinouye@google.com>
Date: Sat, 7 Mar 2026 22:31:24 -0800
Subject: [PATCH] Docs: Add documentation for notifications
 (experimental)(macOS) (#21163)

---
 docs/cli/notifications.md | 58 +++++++++++++++++++++++++++++++++++++++
 docs/sidebar.json         |  5 ++++
 2 files changed, 63 insertions(+)
 create mode 100644 docs/cli/notifications.md

diff --git a/docs/cli/notifications.md b/docs/cli/notifications.md
new file mode 100644
index 0000000000..8326a1efb2
--- /dev/null
+++ b/docs/cli/notifications.md
@@ -0,0 +1,58 @@
+# Notifications (experimental)
+
+Gemini CLI can send system notifications to alert you when a session completes
+or when it needs your attention, such as when it's waiting for you to approve a
+tool call.
+
+> **Note:** This is a preview feature currently under active development.
+> Preview features may be available on the **Preview** channel or may need to be
+> enabled under `/settings`.
+
+Notifications are particularly useful when running long-running tasks or using
+[Plan Mode](./plan-mode.md), letting you switch to other windows while Gemini
+CLI works in the background.
+
+## Requirements
+
+Currently, system notifications are only supported on macOS.
+
+### Terminal support
+
+The CLI uses the OSC 9 terminal escape sequence to trigger system notifications.
+This is supported by several modern terminal emulators. If your terminal does
+not support OSC 9 notifications, Gemini CLI falls back to a system alert sound
+to get your attention.
+
+## Enable notifications
+
+Notifications are disabled by default. You can enable them using the `/settings`
+command or by updating your `settings.json` file.
+
+1.  Open the settings dialog by typing `/settings` in an interactive session.
+2.  Navigate to the **General** category.
+3.  Toggle the **Enable Notifications** setting to **On**.
+
+Alternatively, add the following to your `settings.json`:
+
+```json
+{
+  "general": {
+    "enableNotifications": true
+  }
+}
+```
+
+## Types of notifications
+
+Gemini CLI sends notifications for the following events:
+
+- **Action required:** Triggered when the model is waiting for user input or
+  tool approval. This helps you know when the CLI has paused and needs you to
+  intervene.
+- **Session complete:** Triggered when a session finishes successfully. This is
+  useful for tracking the completion of automated tasks.
+
+## Next steps
+
+- Start planning with [Plan Mode](./plan-mode.md).
+- Configure your experience with other [settings](./settings.md).
diff --git a/docs/sidebar.json b/docs/sidebar.json
index 000f571077..7c201e0071 100644
--- a/docs/sidebar.json
+++ b/docs/sidebar.json
@@ -106,6 +106,11 @@
           { "label": "MCP servers", "slug": "docs/tools/mcp-server" },
           { "label": "Model routing", "slug": "docs/cli/model-routing" },
           { "label": "Model selection", "slug": "docs/cli/model" },
+          {
+            "label": "Notifications",
+            "badge": "🔬",
+            "slug": "docs/cli/notifications"
+          },
           { "label": "Plan mode", "badge": "🔬", "slug": "docs/cli/plan-mode" },
           {
             "label": "Subagents",