Josh Ramirez
← Field guide

Entry 07 of 23

Departed Summer 2025

my desktopInfrastructureShipped
Three macOS customization layers shown as large icons labeled hammerspoon, raycast, and Leader key
Three layers: automate the OS, launch the command, make the shortcut physical.

Departure

Stock macOS is good at being neutral. I wanted the opposite: a desktop that knew my routes. The whole setup settled into three apps — Hammerspoon for the things the OS should do automatically, Raycast for the actions I want to search, and Leader Key for the commands my hands should remember.

Approach

4 tools

  • Hammerspoon
  • Raycast
  • Leader Key
  • Lua

No replacement OS, no fragile desktop cosplay. Everything had to sit on top of stock macOS, survive a reboot, and stay simple enough that I would keep using it.

Field log

4 entries

  1. Hammerspoon

    Hammerspoon is the low-level layer: Lua with access to the parts of macOS Apple exposes but does not make pleasant. I use it for the invisible things — window movement, device events, menu bar widgets, small automations that should happen without opening an app. The basic pattern is simple: edit init.lua, bind a hotkey or watcher, reload config, let the machine do the repeated motion next time.

    macOS desktop showing iTerm on the left and the Hammerspoon console on the right logging device and screen events
    Hammerspoon is where macOS turns scriptable: windows, USB events, sleep/wake, menu bar, all reachable from Lua.
  2. Raycast

    Raycast replaced Spotlight because Spotlight opens things; Raycast performs things. It is the command palette: clipboard history, calendar, emoji, app launching, custom scripts, and small utilities I do not want living in the dock. The way I use it is intentionally boring: open Raycast, type the verb, press return. If I do something twice in a week, it probably becomes a Raycast command.

    Raycast command center over a red dark background with search suggestions, clipboard history, AI Chat, emoji search, calendar, store, and window management commands
    Raycast is the searchable layer: commands, snippets, clipboard, scripts, and app actions in one bar.
  3. Leader Key

    Leader Key is for actions that should not require search at all. I use it like a keyboard-native menu: press the leader, then a small sequence. In the screenshot, t opens Terminal, and the o group fans out into Safari, Mail, Music, and Messages. Raycast is for remembering a command by name; Leader Key is for the things my hands already know.

    Leader Key Settings window showing keyboard sequences mapped to Terminal, Safari, Mail, Music, and Messages
    A small routing table for muscle memory: leader, then the shortest path to the app or action.
  4. The sendoff

    The moral is not that macOS needs to look different. It needs to take fewer negotiations. Hammerspoon handles the background behavior, Raycast handles the searchable command surface, and Leader Key handles the repeated paths. When the three agree, the desktop stops being a place I manage and becomes the thing carrying the work forward.

From the gallery

4 figures

Hammerspoon, Raycast, and Leader Key icons arranged as the three layers of the macOS setup
The full map: Hammerspoon underneath, Raycast in the middle, Leader Key in the hands.
Hammerspoon console beside a terminal window on macOS
Hammerspoon: script the OS.
Raycast search and command interface with suggestions and commands
Raycast: search the command.
Leader Key settings with sequences mapped to macOS applications
Leader Key: memorize the route.

What I came back with

Three layers: OS automation, command palette, muscle memory.

Lesson from the terrain

macOS ships as a default-shaped computer. Hammerspoon, Raycast, and Leader Key turn it into a personal system without replacing the OS. Each tool closes a different kind of gap: the OS doing repeated work for me, the launcher finding the command faster than I can browse for it, and the keyboard making frequent actions automatic. The point of customization is not decoration; it is removing the tiny delays until the computer feels like it is already on my side.

Cross-links