AppBadgeWatcher Spoon

A Hammerspoon Spoon that monitors app dock badges and displays notification counts in your menu bar.

Repository: https://github.com/hugoh/AppBadgeWatcher.spoon

Features

• Monitors dock badge values of specified applications
• Displays one menu bar item per app with badges: the app icon plus a superscript count (subscript for snoozed). The count is drawn as menu bar text, so it always matches the menu bar's light/dark color
• Drag items to reorder them; positions are remembered across restarts
• Configurable refresh interval
• "Snooze" badge counts by clicking menu bar item

Alternatives

If you're looking for other solutions in this space, consider:

• Doll - Native macOS app with similar functionality
• Badgeify - Commercial alternative on Mac App Store

AppBadgeWatcher aims to provide a Hammerspoon-powered, configurable, lightweight option.

Installation

Ensure you have Hammerspoon installed, then choose a method:

Release zip (recommended)

1. Download AppBadgeWatcher.spoon.zip from the latest release
2. Unzip — this produces an AppBadgeWatcher.spoon folder
3. Move it to ~/.hammerspoon/Spoons/
4. Reload Hammerspoon (menu bar icon → Reload Config, or run hs.reload() in the console)

SpoonInstall (if you already use it)

spoon.SpoonInstall:installSpoonFromZip(
  "https://github.com/hugoh/AppBadgeWatcher.spoon/releases/latest/download/AppBadgeWatcher.spoon.zip"
)

Clone from git (for development or latest changes)

cd ~/.hammerspoon/Spoons
git clone https://github.com/hugoh/AppBadgeWatcher.spoon.git

Configuration

Below is a sample configuration to add this to your .hammerspoon/init.lua:

-- Load the Spoon
hs.loadSpoon("AppBadgeWatcher")

-- Configure watched apps and settings
spoon.AppBadgeWatcher.appsToWatch = {
    "Slack",
    "Microsoft Teams",
}
-- Optional: default configuration showed below
spoon.AppBadgeWatcher.refreshInterval = 15  -- Update every 15 seconds while a watched app runs
spoon.AppBadgeWatcher.nothingIndicator = "・"  -- Shown when no notifications
spoon.AppBadgeWatcher.grayscaleIcon = false  -- Convert app icons to grayscale?
spoon.AppBadgeWatcher.infiniteThreshold = 9  -- Counts above this show as ⁺ instead of the number
spoon.AppBadgeWatcher.snoozeOnClick = true  -- Clicking an app's menu bar item snoozes its badge

-- Start the watcher
spoon.AppBadgeWatcher:start()

The same settings can be passed as a table to :configure(), which returns the spoon so calls can be chained:

hs.loadSpoon("AppBadgeWatcher")
spoon.AppBadgeWatcher:configure({
    appsToWatch = { "Slack", "Microsoft Teams" },
    infiniteThreshold = 9,
}):start()

How It Works

The Spoon periodically checks the Dock's accessibility elements for badge values on specified applications. Key features:

• Smart Polling: Checks at configured intervals (default 15s)
• Icon Cache: App icons are cached for better performance
• Compact Display: Shows a ⁺ sign for counts over the configurable infiniteThreshold (default 9)
• Low Profile: Displays subtle dot when no notifications exist

Security & Permissions

This Spoon requires Accessibility API access to:

• Monitor dock badge values
• Update menu bar indicators

Enable access in:

1. System Settings → Privacy & Security → Accessibility
2. Add Hammerspoon to the allowed apps list

API documentation

Full API reference is available at https://appbadgewatcher-spoon.larve.net/.