What This Project Does

This is a keyboard customization system that reimagines how your Mac keyboard works. Instead of using your keyboard the standard way—where each key does one fixed thing—this project lets you create custom keyboard "modes" that unlock faster, more efficient typing anywhere on your computer. The goal is simple: make your hands stay on the home row (the middle row where your fingers rest naturally) so you never have to move them to reach common commands.

How It Works

The project combines two pieces of software on macOS. Karabiner-Elements remaps your physical keys—for example, turning the useless Caps Lock key into something actually useful. Hammerspoon layers additional smart behaviors on top: when you hold certain keys together or press specific combinations, your keyboard transforms into a temporary "mode" with entirely different behaviors. Think of it like having a secret menu inside your keyboard. For instance, pressing and holding S and D together activates "Super Duper Mode," where H, J, K, L suddenly control cursor movement (arrow keys), instead of typing letters.

Who Would Use This

This is for people on macOS who spend a lot of time typing and want to work faster without reaching for the mouse or moving their hands around the keyboard. A software developer might use Window Layout Mode to snap open windows to the left or right half of the screen with just a few keypresses. Someone writing blog posts or comments might activate Markdown Mode to quickly wrap selected text in asterisks or backticks. The customization philosophy here is personal—the author set this up for themselves, but every piece is configurable so you can remap it to launch your own favorite apps or perform your own frequent actions.

Notable Design Choices

The project is written in Lua and lives in configuration files rather than as a standalone app. This means it's lightweight and runs in the background, modifying how your OS interprets keyboard input at a low level. It only works on macOS and requires some setup (installing Karabiner-Elements, granting accessibility permissions), but once running, the muscle memory applies everywhere—in your editor, terminal, browser, and any other app. That consistency is the whole point: you shouldn't have to think about how to move the cursor or launch an app; your hands just know.