mokr (MacOs Keyboard Remapper) ⌨️

A high-performance, low-level macOS keyboard remapper designed to turn the useless Caps Lock key into a power-user navigation layer. Designed for environments where you are restricted from installing third-party software but have the freedom to run your own compiled binaries.

Note: This entire project was 100% vibe coded. ## ✨ Features

• Vim Navigation: Use HJKL as Arrow keys when Caps Lock (remapped to Control) is held.
• Smart Jumps: Supports Option and Shift modifiers while using Vim navigation for word selection.
• Tab & Line Navigation: [ and ] act as Cmd+Left/Right for instant browser tab switching or jumping to the start/end of lines.
• Screenshot UI: CapsLock + P triggers the macOS screenshot utility (Cmd+Shift+5).
• Flamoji Trigger: CapsLock + . induces the Flamoji picker. Can rebind to show the native MacOS emoji panel as well (which sucks btw).
• Zero Latency: Built with CoreGraphics for hardware-level event manipulation.

---

🏗 Architecture

mokr operates at the lowest possible user-space layer on macOS:

1. CGEventTap (HID Level): The tool hooks into the .cgSessionEventTap stream at the .headInsertEventTap position. This ensures mokr intercepts hardware keystrokes before they are processed by the system or any other application.
2. Event Transformation: When the "Control" modifier (remapped Caps Lock) is detected, mokr swallows the original event by returning nil to the system and uses CGEvent.post() to inject new, remapped hardware events into the stream.
3. Ghost Process: Compiled as a native Swift binary, it runs as a detached background process with a near-zero memory footprint.

---

🚀 Installation & Build

1. Prerequisite: Caps Lock Remap

You must first remap your Caps Lock key to Control via macOS System Settings: System Settings > Keyboard > Keyboard Shortcuts... > Modifier Keys > Caps Lock -> Control.

2. Build and Install

This project uses a standard Makefile to compile and stash the binary in a hidden directory.

make install

3. Permissions

Because mokr intercepts hardware events, you must grant Accessibility permissions to the mokr binary (or your Terminal app) in: System Settings > Privacy & Security > Accessibility.

---

⌨️ Mapping Table

Combination	Result	Description
Caps + H/J/K/L	← / ↓ / ↑ / →	Vim-style arrow movement
Caps + [	Cmd + ←	Home / Previous Tab
Caps + ]	Cmd + →	End / Next Tab
Caps + P	Cmd + Shift + 5	Screenshot Selection UI
Caps + .	Cmd + Opt + E	Open Flamoji Panel

---

🛑 Management

• Stop: make stop
• Full Uninstall: make clean

Known issue: Command-based Home/End behavior ([ and ]) may vary in specific Terminal emulators depending on their internal keybinding overrides.