#Notificaciones

cmux soporta notificaciones de escritorio, permitiendo que agentes de IA y scripts le alerten cuando necesitan atención.

#Ciclo de vida

Recibida: la notificación aparece en el panel, se dispara la alerta de escritorio (si no está suprimida)
No leída: se muestra una insignia en la pestaña del workspace
Leída: se borra cuando visualiza ese workspace
Borrada: eliminada del panel

#Supresión

Las alertas de escritorio se suprimen cuando:

La ventana de cmux está enfocada
El workspace específico que envía la notificación está activo
El panel de notificaciones está abierto

#Panel de notificaciones

Presione ⌘⇧I para abrir el panel de notificaciones. Haga clic en una notificación para saltar a ese workspace. Presione ⌘⇧U para saltar directamente al workspace con la notificación no leída más reciente.

#Comando personalizado

Ejecute un comando de shell cada vez que se programe una notificación. Configúrelo en Configuración > App > Comando de notificación. El comando se ejecuta vía /bin/sh -c con estas variables de entorno:

Variable	Descripción
`CMUX_NOTIFICATION_TITLE`	Título de notificación (nombre del workspace o nombre de la app)
`CMUX_NOTIFICATION_SUBTITLE`	Subtítulo de notificación
`CMUX_NOTIFICATION_BODY`	Texto del cuerpo de la notificación

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

El comando se ejecuta independientemente del selector de sonido del sistema. Configure el selector en "Ninguno" para usar solo el comando personalizado, o mantenga ambos para un sonido del sistema más una acción personalizada.

#Hooks de notificación

cmux.json puede definir hooks de notificación que reciben cada política de notificación como JSON por stdin. Cada hook devuelve JSON por stdout. Los hooks están desactivados de forma predeterminada; cmux solo los ejecuta cuando notifications.hooks contiene al menos un hook habilitado. cmux aplica el texto y los efectos devueltos, para que los hooks puedan filtrar banners, conservar u omitir el historial de la barra lateral, reproducir sonidos o detener hooks posteriores.

cmux.json

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

Entrada y salida del hook

{
  "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
  },
  "effects": {
    "record": true,
    "markUnread": true,
    "reorderWorkspace": true,
    "desktop": true,
    "sound": true,
    "command": true,
    "paneFlash": true
  }
}

Los hooks se heredan desde el archivo global ~/.config/cmux/cmux.json y los archivos de proyecto .cmux/cmux.json, desde los directorios padre hasta el espacio de trabajo actual. Los hooks de proyecto usan el mismo aviso de confianza que otros comandos de proyecto en cmux.json antes de ejecutarse. Los banners de aprobación de Feed también pasan por estos hooks; desactivar desktop suprime el banner nativo y mantiene el elemento de Feed disponible en cmux. Configura notifications.hooksMode como replace en un proyecto para ignorar hooks heredados. Si un hook falla, agota el tiempo o devuelve JSON no válido, cmux usa el comportamiento de notificación predeterminado y muestra una alerta de fallo del hook.

#Enviar notificaciones

#CLI

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

#OSC 777 (simple)

El protocolo RXVT usa un formato fijo con título y cuerpo:

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 (avanzado)

El protocolo Kitty soporta subtítulos e IDs de notificación:

# 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\\'

Característica	OSC 99	OSC 777
Título + cuerpo	Sí	Sí
Subtítulo	Sí	No
ID de notificación	Sí	No
Complejidad	Mayor	Menor

Use OSC 777 para notificaciones simples. Use OSC 99 cuando necesite subtítulos o IDs de notificación. Use la CLI (cmux notify) para la integración más sencilla.

#Hooks de Claude Code

cmux se integra con Claude Code mediante hooks para notificarle cuando las tareas se completan.

#1. Crear el script de hook

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

#!/bin/bash
# Skip if not in cmux
[ -S /tmp/cmux.sock ] || exit 0

EVENT=$(cat)
EVENT_TYPE=$(echo "$EVENT" | jq -r '.hook_event_name // "unknown"')
TOOL=$(echo "$EVENT" | jq -r '.tool_name // ""')

case "$EVENT_TYPE" in
    "Stop")
        cmux notify --title "Claude Code" --body "Session complete"
        ;;
    "PostToolUse")
        [ "$TOOL" = "Task" ] && cmux notify --title "Claude Code" --body "Agent finished"
        ;;
esac

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

#2. Configurar Claude Code

~/.claude/settings.json

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/cmux-notify.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Task",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/cmux-notify.sh"
          }
        ]
      }
    ]
  }
}

Reinicie Claude Code para aplicar los hooks.

#GitHub Copilot CLI

Copilot CLI soporta hooks que ejecutan comandos shell en eventos del ciclo de vida como el envío de prompts, la detención del agente y errores.

~/.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
      }
    ]
  }
}

Para hooks a nivel de repositorio, cree un archivo .github/hooks/notify.json con la misma estructura:

.github/hooks/notify.json

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

#Ejemplos de integración

#Notificar después de un comando largo

~/.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');

#Passthrough de tmux

Si usa tmux dentro de cmux, habilite passthrough:

.tmux.conf

set -g allow-passthrough on

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