desktop-notify - SKILL.md Agent Skill

name: desktop-notify description: Send desktop notifications (macOS/Linux) with a project-title wrapper.

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:

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

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

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

Supported entrypoints for this skill are only:

scripts/project-notify.sh
scripts/desktop-notify.sh

Keep docs/examples pinned to those two paths so script regression + smoke coverage stays accurate.

Quick local sanity check:

test -x "$AGENT_HOME/skills/tools/notifications/desktop-notify/scripts/project-notify.sh"
test -x "$AGENT_HOME/skills/tools/notifications/desktop-notify/scripts/desktop-notify.sh"

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 $AGENT_HOME/skills/tools/notifications/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