Departed Summer 2025
macOS Customization
my desktop · Infrastructure · Shipped
[image: Single white keyboard keycap with a black dot painted in the center — the 'leader key']
Departure
Stock macOS hands you Spotlight, a fixed menu bar, and a dock. I wanted a launcher for everything I do, a menu bar that surfaced what I actually look at, and one keycap that was the front door to all of it.
Approach
- Hammerspoon
- Raycast
- Lua
- Karabiner
No replacement OS, no jailbreak — everything had to sit on top of stock macOS and survive a reboot.
Field log
Jun 12, 2025
Installed Hammerspoon. The first three lines of Lua I'd ever written bound cmd-alt-ctrl-arrows to half-screen and full-screen — and replaced the only paid window manager I'd ever cared about.
[image: Hammerspoon configuration window showing a Lua script for window placement on macOS]
init.lua opened to the window-placement bindings — the first real Lua I ever shipped. Jun 21, 2025
Routed the keycap with the black dot through Karabiner into a hyper key, then made it the entry point to a leader sequence. 'leader-w-c' centers a window, 'leader-w-h' sends it left, 'leader-p' jumps to a project. By day four my hands had stopped looking.
Jul 3, 2025
Used Hammerspoon's menubar API to draw my own widgets across the top: a stock ticker, the local IP, the weather, the battery as an actual number. Apple wastes that strip; I wanted it earning rent.
[image: Custom macOS menu bar — stock ticker, local IP, 85°F weather, battery percentage]
Top of the screen, refreshed every minute: ticker, IP, 85°F, battery %. Jul 18, 2025
Pinned a grid of widgets to the desktop itself — Notion for the day's notes, the folders I open most, Zoom for the next call, Roblox because a friend kept asking. The desktop is the first thing I see; it should already know what I'm about to do.
[image: Custom macOS desktop with widgets in a grid layout: folders, Notion, Roblox, Zoom]
The desktop turned into a dashboard — folders, Notion, Roblox, Zoom, all in arm's reach. Aug 5, 2025
Moved off Spotlight entirely. Pointed Raycast at a folder of small shell and AppleScript snippets — 'new-project', 'mute-zoom', 'pick-color' — and the search bar started overlaying Slides, my IDE, whatever I had focused.
[image: Raycast search bar overlaid on Google Slides showing custom script options]
Raycast on top of Slides, surfacing the scripts I wrote that morning. Aug 24, 2025
Reboots stopped wiping the setup — init.lua loads on login, Karabiner remembers the leader, Raycast restores its scripts. Most of what I used to click is now three keystrokes I don't think about.
From the gallery
[image: Three logos in a row: Hammerspoon (yellow hammer-and-spoon), Raycast (dark red), and a single leader keycap]
[image: Terminal window running a small custom shell script mapped through Raycast]
What I came back with
Desktop as system
Lesson from the terrain
macOS ships as a default-shaped computer; a few hundred lines of Lua and one remapped keycap turn it into a Josh-shaped one. Hammerspoon, Raycast, and the leader key aren't really three tools — they're the same idea applied at three layers (OS, launcher, keyboard), each one closing a small gap between what I want and what the machine does. Once the gaps close, you stop noticing the computer.