Hammerspoon Menu Bar Customization: Build Your Own Status Indicators

Custom Menu Bar Basics

Create custom menu bar items in Hammerspoon — show battery, network, or any shell output as live status indicators written in Lua.

Hammerspoon bridges macOS internals to Lua. You get window management, clipboard, automation triggers, and system events — all scriptable.

By the end of this 9 min guide, you'll have a working Hammerspoon setup and practical Hammerspoon workflows you can use immediately.

• Understand what Hammerspoon does and why it matters for System
• Install and configure Hammerspoon for your environment
• Build Hammerspoon-specific workflows with real examples
• Troubleshoot common Hammerspoon issues with concrete fixes

Setting Up hs.menubar in init.lua

Install Hammerspoon:

brew install --cask hammerspoon

• System environment with appropriate permissions
• No prior Hammerspoon experience needed
• A terminal with true color support
• Git for version-controlling your config

Building Status Indicators

Your init.lua is the entry point. Split large configs into modules under lua/ and require them. Set hs.window.animationDuration = 0 for instant snapping.

Here's a foundational configuration to start with:

-- init.lua
hs.window.animationDuration = 0
hs.hotkey.bind({"cmd","alt"}, "left", function()
local f = hs.window.focusedWindow():frame()
local s = hs.window.focusedWindow():screen():frame()
f.x, f.y, f.w, f.h = s.x, s.y, s.w/2, s.h
hs.window.focusedWindow():setFrame(f)
end)

• Begin with this config and make small, incremental changes
• Document each setting with inline comments
• Test changes one at a time to isolate issues
• Keep your config in a Git repo for easy rollback and sharing

Auto-Updating Widgets

With Hammerspoon configured, these Hammerspoon-specific workflows will save you time every day:

• Cmd+Alt+Arrows snap windows to halves
• Window layouts saved and restored per display config
• App switcher with a custom menu
• Clipboard history accessible from anywhere

Click Actions & Dropdown Menus

Once you're comfortable with Hammerspoon basics, these advanced techniques will transform your Hammerspoon workflow:

• Watch for WiFi/network changes with hs.wifi.watcher
• Build menu bar widgets with hs.menubar
• Auto-arrange windows when external displays connect
• Create a hyper key with Karabiner + Hammerspoon

Menu Bar Rendering Issues

Here are the most common Hammerspoon issues and how to fix them:

• Windows not moving? Check Accessibility permissions
• Config errors? Run hs.reload() or check the console
• App not found? Use hs.application.find()
• Menu bar not showing? Check hs.menubar.new() return value

Menu Bar Mastery

Congratulations — you now have a solid Hammerspoon foundation. Here's where to go next:

• Explore the official Hammerspoon documentation for features not covered here
• Join the Hammerspoon community (GitHub Discussions, Discord, or Reddit)
• Check the related tutorials below for deeper Hammerspoon dives
• Build your own Hammerspoon configuration and share it with the community