Hammerspoon Menu Bar

Lightweight Hammerspoon scripts that add real-time system indicators to the macOS menu bar.
Includes 🪫 Low Battery Alert and 🔥 High CPU Usage monitors, both designed for ultra-low overhead and instant responsiveness using native ioreg and shell integrations.

Features

🪫 Low Battery Alert

• Displays a 🪫 icon in the menu bar when battery < 10 %.
• Shows a persistent alert if battery < 3 %.
• Automatically disappears when power is connected.
• Uses direct ioreg reads for instant detection — no delay or caching.
• Optional lightweight polling (only active under 10 %).

🔥 High CPU Monitor

• Monitors the top CPU process every 1 minute.
• Displays a 🔥 menu bar icon if any process exceeds 100 % CPU.
• Tooltip shows the exact process name and CPU percentage.
• Hides itself automatically when usage normalizes.

Both scripts are self-contained, event-driven, and consume < 0.1 % CPU total. Each utility is intentionally small, single-purpose, and can be combined in any configuration.

Requirements

• macOS with Hammerspoon installed
• Hammerspoon accessibility access granted (required for menu bar and alerts)
• Hammerspoon Preferences → Behavior → enable Launch Hammerspoon at login
• Hammerspoon allowed in the menu bar:
  System Settings → Control Center → Menu Bar → Allow in the Menu Bar
  
• Optional: In Hammerspoon Preferences → Behavior, uncheck Show menu icon for a cleaner menu bar
  

Usage

1. Clone or Download

git clone https://github.com/marksowell/hammerspoon-menu-bar.git

2. Copy the Scripts

cp battery.lua cpu.lua ~/.hammerspoon/

3. Load from init.lua

Edit your ~/.hammerspoon/init.lua:

require("battery")
require("cpu")

Reload your config (⌘ + ⌃ + R) or restart Hammerspoon.

Contributing

Contributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes.

License

This project is licensed under the MIT License. See the LICENSE file for details.