desktop-notify

Desktop Notify

Contract

Prereqs:

• bash available on PATH.
• Notification backend:
  • macOS: terminal-notifier
  • Linux: notify-send

Inputs:

• Message string (required) and --level info|success|warn|error.
• Optional env: CODEX_DESKTOP_NOTIFY_ENABLED=false to disable; PROJECT_PATH for project title derivation.

Outputs:

• A desktop notification (best-effort); silent no-op when disabled or backend missing.

Exit codes:

• 0: success or no-op
• non-zero: invalid usage or unexpected script/runtime failure

Failure modes:

• Backend not installed (script no-ops by default).
• Notifications disabled via CODEX_DESKTOP_NOTIFY_ENABLED=false.

Use this skill when you need to surface a short status update to the user via a desktop notification.

Prefer using the project wrapper (auto title) to avoid repeating title rules:

$CODEX_HOME/skills/tools/devex/desktop-notify/scripts/project-notify.sh "your short message" --level success

If you need a custom title, call the notifier directly:

$CODEX_HOME/skills/tools/devex/desktop-notify/scripts/desktop-notify.sh \
  --title "custom title" \
  --message "your short message" \
  --level info

Behavior

• macOS: uses terminal-notifier when installed.
• Linux: uses notify-send (libnotify) when installed.
• Missing backend: silent no-op by default.

Environment

• CODEX_DESKTOP_NOTIFY_ENABLED=false: disable notifications (default: enabled)
• CODEX_DESKTOP_NOTIFY_HINTS_ENABLED=true: print a one-line install hint when backend is missing (default: disabled)
• PROJECT_PATH: used by $CODEX_HOME/skills/tools/devex/desktop-notify/scripts/project-notify.sh to derive the project title (fallback: git root, then $PWD)

Install hints

• macOS: brew install terminal-notifier
• Linux (Debian/Ubuntu): sudo apt-get install libnotify-bin
• Linux (Fedora): sudo dnf install libnotify