---
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:

```bash
$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:

```bash
$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:

```bash
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`
