diff --git a/.gitignore b/.gitignore
index 510afb9..d92fd8a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,3 @@
 result
 .build/
+mac-agent/.venv/
diff --git a/mac-agent/README.md b/mac-agent/README.md
new file mode 100644
index 0000000..f100ba3
--- /dev/null
+++ b/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
+```
diff --git a/mac-agent/com.user.kb-focus.plist b/mac-agent/com.user.kb-focus.plist
deleted file mode 100644
index f8ad529..0000000
--- a/mac-agent/com.user.kb-focus.plist
+++ /dev/null
@@ -1,21 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-    <key>Label</key>
-    <string>com.user.kb-focus</string>
-    <key>ProgramArguments</key>
-    <array>
-        <string>/usr/bin/python3</string>
-        <string>kb-focus.py</string>
-    </array>
-    <key>WorkingDirectory</key>
-    <string>/Users/USER/keyboard/mac-agent</string>
-    <key>KeepAlive</key>
-    <true/>
-    <key>StandardOutPath</key>
-    <string>/tmp/kb-focus.stdout.log</string>
-    <key>StandardErrorPath</key>
-    <string>/tmp/kb-focus.stderr.log</string>
-</dict>
-</plist>
diff --git a/mac-agent/install.sh b/mac-agent/install.sh
new file mode 100755
index 0000000..9ae07dc
--- /dev/null
+++ b/mac-agent/install.sh
@@ -0,0 +1,48 @@
+#!/bin/bash
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+LABEL="com.user.kb-focus"
+PLIST="$HOME/Library/LaunchAgents/$LABEL.plist"
+VENV="$SCRIPT_DIR/.venv"
+
+# Create venv and install dependencies
+if [ ! -d "$VENV" ]; then
+    echo "Creating virtualenv..."
+    python3 -m venv "$VENV"
+fi
+echo "Installing dependencies..."
+"$VENV/bin/pip" install -q -r "$SCRIPT_DIR/requirements.txt"
+
+# Unload existing agent if present
+launchctl bootout "gui/$(id -u)/$LABEL" 2>/dev/null || true
+
+# Generate plist with correct paths
+cat > "$PLIST" <<EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>$LABEL</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>$VENV/bin/python3</string>
+        <string>-u</string>
+        <string>$SCRIPT_DIR/kb-focus.py</string>
+    </array>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>/tmp/kb-focus.stdout.log</string>
+    <key>StandardErrorPath</key>
+    <string>/tmp/kb-focus.stderr.log</string>
+</dict>
+</plist>
+EOF
+
+# Load agent
+launchctl bootstrap "gui/$(id -u)" "$PLIST"
+
+echo "Installed and started $LABEL"
+echo "Logs: /tmp/kb-focus.stdout.log, /tmp/kb-focus.stderr.log"
diff --git a/mac-agent/uninstall.sh b/mac-agent/uninstall.sh
new file mode 100755
index 0000000..f1d66e0
--- /dev/null
+++ b/mac-agent/uninstall.sh
@@ -0,0 +1,10 @@
+#!/bin/bash
+set -e
+
+LABEL="com.user.kb-focus"
+PLIST="$HOME/Library/LaunchAgents/$LABEL.plist"
+
+launchctl bootout "gui/$(id -u)/$LABEL" 2>/dev/null || true
+rm -f "$PLIST"
+
+echo "Uninstalled $LABEL"