From 9d8e6a8d05143d92a053a415f1313aeddbb33ab6 Mon Sep 17 00:00:00 2001
From: Harley Adams <Harley-Adams@users.noreply.github.com>
Date: Thu, 26 Mar 2026 15:49:36 -0700
Subject: [PATCH] docs: add Copilot CLI hook setup to notifications guide
 (#1875)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* docs: add Copilot CLI hook setup to notifications guide

Add GitHub Copilot CLI section with hooks for notifications and
sidebar status pills (userPromptSubmitted, agentStop, errorOccurred,
sessionEnd). Includes link to official GitHub hooks documentation.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* docs: address PR feedback for Copilot CLI hooks

- Use if/else instead of &&/|| to avoid false-positive osascript fallback
- Fix jq path: .error.message → .errorMessage for Copilot CLI schema
- Remove --icon/--color flags (let cmux handle styling)
- Add clear-notifications side-effect note
- Add concrete repo-level config example
- Document set-status/clear-status in CLI Commands section

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Harley Adams <harley.adams@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 docs/notifications.md | 53 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/docs/notifications.md b/docs/notifications.md
index d6926d36..250e11dd 100644
--- a/docs/notifications.md
+++ b/docs/notifications.md
@@ -58,6 +58,57 @@ cmux notify --title "Done" --tab 0 --panel 1
 
 See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code) for hook configuration.
 
+### GitHub Copilot CLI
+
+Copilot CLI supports [hooks](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks) that run shell commands at key lifecycle events. Add to `~/.copilot/config.json`:
+
+```json
+{
+  "hooks": {
+    "userPromptSubmitted": [
+      {
+        "type": "command",
+        "bash": "if command -v cmux &>/dev/null; then cmux set-status copilot_cli Running; fi",
+        "timeoutSec": 3
+      }
+    ],
+    "agentStop": [
+      {
+        "type": "command",
+        "bash": "if command -v cmux &>/dev/null; then cmux notify --title 'Copilot CLI' --body 'Done'; cmux set-status copilot_cli Idle; else osascript -e 'display notification \"Done\" with title \"Copilot CLI\"'; fi",
+        "timeoutSec": 5
+      }
+    ],
+    "errorOccurred": [
+      {
+        "type": "command",
+        "bash": "if command -v cmux &>/dev/null; then cmux notify --title 'Copilot CLI' --subtitle 'Error' --body \"$(cat | jq -r '.errorMessage // \"An error occurred\"' 2>/dev/null | head -c 100)\"; cmux set-status copilot_cli Error; else osascript -e 'display notification \"An error occurred\" with title \"Copilot CLI\"'; fi",
+        "timeoutSec": 5
+      }
+    ],
+    "sessionEnd": [
+      {
+        "type": "command",
+        "bash": "if command -v cmux &>/dev/null; then cmux clear-status copilot_cli; fi",
+        "timeoutSec": 3
+      }
+    ]
+  }
+}
+```
+
+Or for repo-level hooks, create `.github/hooks/notify.json`:
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "userPromptSubmitted": [ ... ],
+    "agentStop": [ ... ]
+  }
+}
+```
+
 ### OpenAI Codex
 
 Add to `~/.codex/config.toml`:
@@ -119,6 +170,8 @@ cmux sets these in child shells:
 cmux notify --title <text> [--subtitle <text>] [--body <text>] [--tab <id|index>] [--panel <id|index>]
 cmux list-notifications
 cmux clear-notifications
+cmux set-status <key> <value>
+cmux clear-status <key>
 cmux ping
 ```