Add install script for mac-agent

mac-agent/README.md

@@ -0,0 +1,40 @@
+# mac-agent
+
+A lightweight macOS daemon that tells the keyboard which app is focused, enabling per-app keyboard behavior (e.g. skipping Ctrl→Cmd rewrites in terminal apps).
+
+## How it works
+
+The script polls the frontmost application every 250ms and sends its name to the keyboard over Raw HID. The keyboard firmware maps app names to an enum and adjusts shortcut behavior accordingly.
+
+## Requirements
+
+- macOS
+- Python 3
+- `hidapi` system library: `brew install hidapi`
+
+## Quick test
+
+```bash
+cd mac-agent
+python3 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+.venv/bin/python3 kb-focus.py
+```
+
+Switch between apps — you should see `App: <name>` printed on each change.
+
+## Install as login agent
+
+```bash
+./install.sh
+```
+
+This creates a virtualenv, installs dependencies, and registers a LaunchAgent that starts on login and auto-restarts on crash.
+
+Logs: `/tmp/kb-focus.stdout.log`, `/tmp/kb-focus.stderr.log`
+
+## Uninstall
+
+```bash
+./uninstall.sh
+```