HeadlinesBriefing favicon HeadlinesBriefing.com

Zen Mode Hammerspoon Script Adds Global Focus to macOS

Hacker News •
×

Developer Ryan released Zen Mode, a Hammerspoon script that adds a system-wide focus mode to macOS with a single hotkey. Pressing Option + Cmd + Z centers the active window at full height while fading the Menu Bar, Dock, wallpaper, and all other windows to black. The script works across every application — terminal, browser, PDF reader, or editor — without per-app configuration. Exiting via the same hotkey or Esc restores the window to its exact previous position and size.

The implementation draws a full-screen Core Graphics canvas at the cursor window level, punching a transparent rounded-corner cutout around the focused window. The ~250 lines of Lua run a custom 60 Hz animation clock that choreographs a two-phase transition: the window glides to center at its original width while the backdrop fades, then grows to full height once the screen is dark. Move and resize durations are tunable. The cutout tracks live window frames each frame to prevent bright seams, and uses a generous corner Radius = 24 to accommodate macOS 26 "Tahoe"'s rounder window corners.

Installation requires brew install --cask hammerspoon, granting Accessibility permissions, and appending the init.lua from the GitHub repository to ~/.hammerspoon/init.lua. The script is dependency-free and readable in minutes. Prior art includes passive dimmers like Haze Over and Focus Dim, Hammerspoon's built-in hs.window.highlight isolate mode, and app-specific zen modes in VS Code, Obsidian, and iA Writer — none of which combine window centering, full-height framing, and Menu Bar/Dock hiding in a single reversible gesture across all apps.