notify

SpecSwarm Notify

Sends a notification using whatever mechanism is available — convocli-notifier plugin (preferred), then notify-send (Linux libnotify), then osascript (macOS), then a terminal bell + stderr message.

Project-agnostic — works on any project regardless of installed plugins. Silent no-op only if none of the four tiers is available, which is rare.

Fire the notification

PLUGIN_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
LIB="${PLUGIN_DIR}/lib/notify.sh"

if [ ! -f "$LIB" ]; then
  echo "❌ notify.sh helper not found at $LIB" >&2
  exit 2
fi

# Parse arguments
URGENCY="info"
TITLE="SpecSwarm"
MESSAGE=""

while [ $# -gt 0 ]; do
  case "$1" in
    --urgent) URGENCY="urgent"; shift ;;
    --success) URGENCY="success"; shift ;;
    --info) URGENCY="info"; shift ;;
    --title) TITLE="$2"; shift 2 ;;
    -h|--help)
      cat <<EOF
Usage: /ss:notify [--urgent|--success|--info] [--title TITLE] [MESSAGE]

Fires a notification using the best-available channel.

Examples:
  /ss:notify "P1.3 ready for review"
  /ss:notify --urgent "Build broke at T012"
  /ss:notify --success --title "Chunk shipped" "P1.3 merged to main"
EOF
      exit 0
      ;;
    *)
      if [ -z "$MESSAGE" ]; then
        MESSAGE="$1"
      else
        MESSAGE="$MESSAGE $1"
      fi
      shift
      ;;
  esac
done

# shellcheck disable=SC1090
source "$LIB"

if ! ss_notify_available; then
  echo "⚠️  No notification mechanism available. Falling back to terminal bell + stderr."
fi

if ss_notify "$URGENCY" "$TITLE" "$MESSAGE"; then
  echo "🔔 Notified [${URGENCY}] ${TITLE}: ${MESSAGE}"
else
  echo "(notification suppressed — debounced within last ${SS_NOTIFY_DEBOUNCE:-10}s)"
fi

Why this exists

The convocli-notifier plugin (when installed) already fires on every Claude Code Stop event — so you get a chime each time Claude finishes responding. That's the baseline.

/ss:notify adds semantic notifications on top: differentiated sounds for urgent/success/info, plus the ability to fire from inside a long-running workflow at a specific moment (e.g., midway through /ss:build when a strategic decision is needed).