Marcelo Paiva

Tools

Omarchy MacBook Keys

A plugin that makes an old MacBook work like a Mac on Omarchy. Every special key does its job again, and the trackpad gets the Mac gestures.

It runs on your MacBook, not in this browser. The code is on GitHub as omarchy-macbook-keys (opens in a new tab).

Listen to this page

3 min listen · 2 min read · Read by a synthetic voice (af_heart, made with Kokoro), from the page’s own words.

A terminal on the MacBook Pro lists its system information beside Omarchy's square lime logo. The hardware is a MacBook Pro (Retina, 15-inch, Late 2013/Mid 2014) with an Intel Core i7-4870HQ at 3.70 GHz, a GeForce GT 750M and 15.5 gigabytes of memory, on a 2880 by 1800 screen. The software is Omarchy 4.0.6-1 on Linux 7.2.8, with Hyprland 0.56.2 and the Tokyo Night theme, and the system is two days old.
The MacBook Pro I made it for, as fastfetch reports it on Omarchy. Redrawn from a photo of the screen.

Why I made it

I put Omarchy, a new Linux setup built on Arch Linux and Hyprland, on my 15-inch MacBook Pro from 2014. None of the special keys worked. Brightness, volume, the keyboard light and the workspace key all did nothing.

The hardware was fine. Omarchy didn't know what this old keyboard's keys were for, so I wrote a plugin that gives each one the job it has on a Mac. Then I did the same for the trackpad.

Cheat sheet

The keys
KeyWhat it does
F1 / F2Screen brightness down / up
F3Mission Control: all your workspaces at once
F4Launchpad: the apps menu
F5 / F6Keyboard light down / up
F7 / F8 / F9Previous / play or pause / next
F10 / F11 / F12Mute / volume down / volume up
fn + F1 to F12Plain function keys
Command + QQuit the app
Command + `Next window
Command + Shift + `Previous window
Command + MPut the window away in the scratchpad
Command + Control + MBring it back
The trackpad gestures
GestureWhat it does
Two-finger scrollNatural scrolling: the content follows your fingers
Two-finger click or tapRight-click
Three-finger swipe left or rightMove between workspaces
Three-finger swipe upMission Control: all your workspaces at once
Three-finger swipe downShow or hide the scratchpad
Four-finger pinch inLaunchpad: the apps menu
Four-finger spreadShow the desktop: the nearest empty workspace
Command + three-finger pinchZoom the screen around the cursor
Three-finger dragSwitched off, because it needs the same fingers as the swipes

Two of the gestures are there for accessibility. Command and a three-finger pinch zooms the screen around the cursor, so you can see something bigger without changing anything else. Three-finger drag moves a window or selects text without holding the trackpad down. It's included but switched off, the same as on a Mac.

Install

git clone https://github.com/mpaiva/omarchy-macbook-keys.git
cd omarchy-macbook-keys
./install.sh

The installer asks for your password for three system steps. Add --no-hyprexpo to skip the F3 workspace view, or --no-trackpad to skip the gestures. To take it all out, run ./uninstall.sh. It puts everything back.

Before you install

I've tested it on one machine, my 2014 MacBook Pro. It should work on most MacBooks and on Apple's own keyboards, because Linux drives them the same way, but I haven't seen it run on any of them.

The F3 workspace view is a plugin of its own, and it has to match your version of Hyprland. After an Omarchy update, F3 stops working until you run hyprpm update.

Omarchy MacBook Keys

This is a manual page for a plugin. It runs on a MacBook, not here, so the page is its cheat sheet and how to install it.

From top to bottom

  1. At the top, the site header: my name, which goes home, then links to Writing, Work, Signal, Tools and Resume, then Settings, where you choose the drawings, light or dark, and movement.
  2. A link back to Tools, the name, a sentence on what the plugin does, and a link to its code on GitHub.
  3. A Listen control: play the page read aloud by a synthetic voice, with buttons to go back or forward 15 seconds, a position slider and a speed choice.
  4. A picture of the MacBook Pro it was made for, with its system information, and a caption.
  5. Why I made it: two short paragraphs.
  6. A cheat sheet: a table of the keys and a table of the trackpad gestures, each with what it does. Then a paragraph on the two accessibility gestures.
  7. How to install it, as three commands, and the options.
  8. What it has and has not been tested on, and the one part that can break.
  9. At the bottom, the footer: a note on how this site is built, links to Illustrations, Pens, Concepts and Accessibility, this Describe this page button, then GitHub, LinkedIn and email.

What you can do here

Look up what a key or gesture does, or install the plugin.