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 clean menu bar indicators with app icons
• 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
spoon.AppBadgeWatcher.nothingIndicator = "・"  -- Shown when no notifications
spoon.AppBadgeWatcher.grayscaleIcon = false  -- Convert app icons to grayscale?
spoon.AppBadgeWatcher.fontSize = 6  -- Badge font size
spoon.AppBadgeWatcher.textOffset = { x = 2, y = 0 } -- Text offset on icon

-- Start the watcher
spoon.AppBadgeWatcher: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 ∞ symbol for counts over 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://hugoh.github.io/AppBadgeWatcher.spoon/.