hs.notify

Module for creating and displaying macOS system notifications.

macOS notifications require user permission before they will appear. Request it once (typically at startup) via hs.permissions.requestNotifications() and it will be remembered across sessions:

hs.permissions.requestNotifications().then(granted => {
    if (granted) hs.notify.show("Hammerspoon", "Notifications are enabled!")
})

Quick notification

// Fire and forget
hs.notify.show("Build complete", "Your project compiled successfully.")

// With a callback invoked when the user interacts
hs.notify.show("Build complete", "Click to view the log.", (response) => {
    console.log("User tapped:", response.actionIdentifier)
})

Rich notification

const n = hs.notify.create({
    title:    "New message",
    subtitle: "From Alice",
    body:     "Are you free tonight?",
    sound:    true,
    threadIdentifier: "messages-alice",
    actions: [
        { identifier: "REPLY", title: "Reply", textInput: true,
          textInputButtonTitle: "Send", textInputPlaceholder: "Type a reply…" },
        { identifier: "DISMISS", title: "Dismiss", destructive: true }
    ],
    callback: (response) => {
        if (response.actionIdentifier === "REPLY") {
            console.log("Reply text:", response.userText)
        }
    }
})
n.send()
// Later, if needed:
n.withdraw()

Callback response object

The callback function receives a single object with these properties:

Options for create()

Triggers

Pass a trigger object in create()'s options to schedule the notification instead of delivering it Time interval — deliver after a fixed delay in seconds (minimum 60 s):

trigger: { type: "timeInterval", interval: 300 }

Calendar — deliver at a specific date/time. Provide either a JS Date object or individual date-component keys; any omitted component matches every value:

// At a specific moment
trigger: { type: "calendar", date: new Date("2026-06-01T09:00:00") }

// At 09:00 on the next day that matches (e.g. next Monday, weekday 2)
trigger: { type: "calendar", weekday: 2, hour: 9, minute: 0 }

Supported component keys: year, month, day, hour, minute, second, weekday.

Action objects