# الإشعارات

يدعم cmux إشعارات سطح المكتب، مما يسمح لوكلاء الذكاء الاصطناعي والنصوص بتنبيهك عندما يحتاجون انتباهك.

## دورة الحياة

1.  مُستلم: يظهر الإشعار في اللوحة، يُطلق تنبيه سطح المكتب (إذا لم يكن مكتوماً)
2.  غير مقروء: تظهر شارة على علامة تبويب مساحة العمل
3.  مقروء: يُمسح عند عرض مساحة العمل تلك
4.  مُمسوح: يُزال من اللوحة

### الكتم

تُكتم تنبيهات سطح المكتب عندما:

-   نافذة cmux مركزة
-   مساحة العمل المحددة التي ترسل الإشعار نشطة
-   لوحة الإشعارات مفتوحة

### لوحة الإشعارات

اضغط `⌘⇧I` لفتح لوحة الإشعارات. انقر على إشعار للانتقال إلى مساحة العمل تلك. اضغط `⌘⇧U` للانتقال مباشرة إلى مساحة العمل التي تحتوي على أحدث إشعار غير مقروء.

## أمر مخصص

تشغيل أمر shell في كل مرة يُجدول فيها إشعار. عيّنه في الإعدادات > التطبيق > أمر الإشعار. يُشغل الأمر عبر /bin/sh -c مع متغيرات البيئة هذه:

| المتغير | الوصف |
| --- | --- |
| `CMUX_NOTIFICATION_TITLE` | عنوان الإشعار (اسم مساحة العمل أو التطبيق) |
| `CMUX_NOTIFICATION_SUBTITLE` | العنوان الفرعي للإشعار |
| `CMUX_NOTIFICATION_BODY` | نص محتوى الإشعار |

Examples

```
# Text-to-speech
say "$CMUX_NOTIFICATION_TITLE"

# Custom sound file
afplay /path/to/sound.aiff

# Log to file
echo "$CMUX_NOTIFICATION_TITLE: $CMUX_NOTIFICATION_BODY" >> ~/notifications.log
```

يعمل الأمر بشكل مستقل عن منتقي صوت النظام. عيّن المنتقي إلى "لا شيء" لاستخدام الأمر المخصص فقط، أو احتفظ بكليهما لصوت نظام مع إجراء مخصص.

## خطافات الإشعارات

يمكن أن يعرّف `cmux.json` خطافات إشعارات تستقبل كل سياسة إشعار كـ JSON عبر stdin. يعيد كل خطاف JSON عبر stdout. تكون الخطافات متوقفة افتراضيًا؛ لا يشغّل cmux أي خطاف إلا عندما يحتوي `notifications.hooks` على خطاف مفعّل واحد على الأقل. يطبق cmux نص الإشعار والتأثيرات المعادة، لذلك يمكن للخطافات تصفية اللافتات، أو الاحتفاظ بسجل الشريط الجانبي أو تخطيه، أو تشغيل الأصوات، أو إيقاف الخطافات اللاحقة.

cmux.json

```
{
  "notifications": {
    "hooks": [
      {
        "id": "quiet-docs",
        "command": "sed 's/"desktop":true/"desktop":false/'",
        "timeoutSeconds": 20
      }
    ]
  }
}
```

إدخال وإخراج الخطاف

```
{
  "version": 1,
  "notification": {
    "workspaceId": "3B3F0D83-...",
    "surfaceId": "7E9C1A02-...",
    "title": "Codex",
    "subtitle": "Waiting",
    "body": "Agent needs input"
  },
  "context": {
    "cwd": "/path/to/project",
    "configPath": "/path/to/project/.cmux/cmux.json",
    "hookId": "quiet-docs",
    "appFocused": false,
    "focusedPanel": false
  },
  "agent": {
    "kind": "claude",
    "category": "turn-complete",
    "pending": false,
    "isSubagent": true
  },
  "effects": {
    "record": true,
    "markUnread": true,
    "reorderWorkspace": true,
    "desktop": true,
    "sound": true,
    "command": true,
    "paneFlash": true
  }
}
```

تُورث الخطافات من الملف العام `~/.config/cmux/cmux.json` وملفات المشروع `.cmux/cmux.json` من المجلدات الأصلية حتى مساحة العمل الحالية. تستخدم خطافات المشروع نفس مطالبة الثقة مثل أوامر المشروع الأخرى في `cmux.json` قبل تشغيلها. تمر لافتات موافقة Feed عبر هذه الخطافات أيضاً؛ يؤدي تعطيل `desktop` إلى منع اللافتة الأصلية مع إبقاء عنصر Feed متاحاً في cmux. اضبط `notifications.hooksMode` على `replace` في إعدادات المشروع لتجاهل الخطافات الموروثة. إذا فشل خطاف أو انتهت مهلته أو أعاد JSON غير صالح، يستخدم cmux سلوك الإشعارات الافتراضي ويعرض تنبيه فشل الخطاف.

### Agent-event context

Notifications that originate from an agent completion signal carry a read-only `agent` object: `kind` is the stable lowercase agent slug (claude, codex, grok, …), `category` is turn-complete, needs-permission, or idle-reminder, `pending` is true when the turn ended with background work still running, and `isSubagent` is true for nested subagent sessions. The object is omitted for non-agent notifications, and the same values are exported to the hook process as CMUX\_NOTIFICATION\_AGENT\_KIND, CMUX\_NOTIFICATION\_AGENT\_CATEGORY, CMUX\_NOTIFICATION\_AGENT\_PENDING, and CMUX\_NOTIFICATION\_AGENT\_IS\_SUBAGENT. For example, this hook silences the banner, sound, and pane flash for subagent completions while leaving everything else untouched:

Silence subagent completions

```
{
  "notifications": {
    "hooks": [
      {
        "id": "mute-subagent-completions",
        "command": "if [ \"${CMUX_NOTIFICATION_AGENT_IS_SUBAGENT-0}\" = \"1\" ] && [ \"$CMUX_NOTIFICATION_AGENT_CATEGORY\" = \"turn-complete\" ]; then printf '{\"effects\":{\"desktop\":false,\"sound\":false,\"paneFlash\":false}}'; fi"
      }
    ]
  }
}
```

With no hooks configured, notification behavior is exactly cmux's built-in default — configuring a hook is the explicit opt-in that hands the delivery decision to your script. Note that cmux's built-in subagent suppression (`automation.suppressSubagentNotifications`, on by default) drops subagent completion events before they reach hooks; turn it off if your hook should see subagent events and make its own decision.

## إرسال الإشعارات

### CLI

```
cmux notify --title "Task Complete" --body "Your build finished"
cmux notify --title "Claude Code" --subtitle "Waiting" --body "Agent needs input"
```

### OSC 777 (بسيط)

يستخدم بروتوكول RXVT تنسيقاً ثابتاً مع عنوان ومحتوى:

```
printf '\e]777;notify;My Title;Message body here\a'
```

Shell function

```
notify_osc777() {
    local title="$1"
    local body="$2"
    printf '\e]777;notify;%s;%s\a' "$title" "$body"
}

notify_osc777 "Build Complete" "All tests passed"
```

### OSC 99 (غني)

يدعم بروتوكول Kitty عناوين فرعية ومعرفات إشعارات:

```
# Format: ESC ] 99 ; <params> ; <payload> ESC \

# Simple notification
printf '\e]99;i=1;e=1;d=0:Hello World\e\\'

# With title, subtitle, and body
printf '\e]99;i=1;e=1;d=0;p=title:Build Complete\e\\'
printf '\e]99;i=1;e=1;d=0;p=subtitle:Project X\e\\'
printf '\e]99;i=1;e=1;d=1;p=body:All tests passed\e\\'
```

| الميزة | OSC 99 | OSC 777 |
| --- | --- | --- |
| العنوان + المحتوى | نعم | نعم |
| العنوان الفرعي | نعم | لا |
| معرّف الإشعار | نعم | لا |
| التعقيد | أعلى | أقل |

استخدم OSC 777 للإشعارات البسيطة. استخدم OSC 99 عندما تحتاج عناوين فرعية أو معرفات إشعارات. استخدم واجهة الأوامر (cmux notify) لأسهل تكامل.

## خطافات Claude Code

يتكامل cmux مع [Claude Code](https://docs.anthropic.com/en/docs/claude-code) عبر الخطافات لإعلامك عند اكتمال المهام.

### 1\. إنشاء نص الخطاف

~/.claude/hooks/cmux-notify.sh

```
#!/bin/bash
# Outside cmux there is no socket to talk to, so do nothing.
[ -S /tmp/cmux.sock ] || exit 0

payload=$(cat)
field() { printf '%s' "$payload" | jq -r "$1 // empty"; }

event=$(field .hook_event_name)
if [ "$event" = "Stop" ]; then
    cmux notify --title "Claude Code" --body "Session complete"
elif [ "$event" = "SubagentStop" ]; then
    cmux notify --title "Claude Code" --body "Agent finished"
fi
```

```
chmod +x ~/.claude/hooks/cmux-notify.sh
```

### 2\. إعداد Claude Code

~/.claude/settings.json

```
{
  "hooks": {
    "SubagentStop": [
      {
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/cmux-notify.sh" }]
      }
    ],
    "Stop": [
      {
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/cmux-notify.sh" }]
      }
    ]
  }
}
```

أعد تشغيل Claude Code لتطبيق الخطافات.

## GitHub Copilot CLI

يدعم Copilot CLI [الخطافات](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks) التي تنفذ أوامر shell عند أحداث دورة الحياة مثل إرسال الأوامر وتوقف الوكيل والأخطاء.

~/.copilot/config.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; fi",
        "timeoutSec": 5
      }
    ],
    "errorOccurred": [
      {
        "type": "command",
        "bash": "if command -v cmux &>/dev/null; then cmux notify --title 'Copilot CLI' --subtitle 'Error' --body 'An error occurred'; cmux set-status copilot_cli Error; fi",
        "timeoutSec": 5
      }
    ],
    "sessionEnd": [
      {
        "type": "command",
        "bash": "if command -v cmux &>/dev/null; then cmux clear-status copilot_cli; fi",
        "timeoutSec": 3
      }
    ]
  }
}
```

لخطافات على مستوى المستودع، أنشئ ملف .github/hooks/notify.json بنفس الهيكل:

.github/hooks/notify.json

```
{
  "version": 1,
  "hooks": {
    "userPromptSubmitted": [ ... ],
    "agentStop": [ ... ]
  }
}
```

## أمثلة التكامل

### إشعار بعد أمر طويل

~/.zshrc

```
# Add to your shell config
notify-after() {
  "$@"
  local exit_code=$?
  if [ $exit_code -eq 0 ]; then
    cmux notify --title "✓ Command Complete" --body "$1"
  else
    cmux notify --title "✗ Command Failed" --body "$1 (exit $exit_code)"
  fi
  return $exit_code
}

# Usage: notify-after npm run build
```

### Python

python

```
import sys

def notify(title: str, body: str):
    """Send OSC 777 notification."""
    sys.stdout.write(f'\x1b]777;notify;{title};{body}\x07')
    sys.stdout.flush()

notify("Script Complete", "Processing finished")
```

### Node.js

node

```
function notify(title, body) {
  process.stdout.write(`\x1b]777;notify;${title};${body}\x07`);
}

notify('Build Done', 'webpack finished');
```

### تمرير tmux

إذا كنت تستخدم tmux داخل cmux، فعّل التمرير:

.tmux.conf

```
set -g allow-passthrough on
```

```
printf '\ePtmux;\e\e]777;notify;Title;Body\a\e\\'
```

Canonical: https://cmux.com/ar/docs/notifications

Documentation index: https://cmux.com/llms.txt