Namespace 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

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

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)
})
Copy

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()
Copy

Callback response object

Options for create()

Triggers

Pass a trigger object in create()'s options to schedule the notification instead of delivering it

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

Calendar* — deliver at a specific date/time. Provide either a JS Date object or individual

// 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 }
Copy

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

Action objects