From 38fb8d8448810806f32fe155df26f3498bc9151c Mon Sep 17 00:00:00 2001
From: Christian Colglazier <christian@cacolglazier.com>
Date: Wed, 14 Oct 2026 07:16:15 -0400
Subject: [PATCH] feat(macos): configure hover window focus

---
 README.md                        | 24 +++++++++++++++++++++++-
 home/.chezmoiignore              |  1 +
 home/dot_Brewfile                |  4 ++++
 home/dot_config/AutoRaise/config | 10 ++++++++++
 4 files changed, 38 insertions(+), 1 deletion(-)
 create mode 100644 home/dot_config/AutoRaise/config

diff --git a/README.md b/README.md
index dc2f60b..eb0b7a7 100644
--- a/README.md
+++ b/README.md
@@ -24,7 +24,7 @@ chezmoi init --apply git@github.com:AquaMorph/dotfiles.git
    ```
 
     The Brewfile includes chezmoi, Git, Emacs, Python, jq, pass, GnuPG, Brave Browser,
-    Alacritty, and Inconsolata. FFmpeg and Ollama are optional; install them separately
+    Alacritty, Inconsolata, and AutoRaise. FFmpeg and Ollama are optional; install them separately
     if needed.
 
 3. Restore your password store to `~/.password-store` and import its GPG private
@@ -63,3 +63,25 @@ To install newly added macOS dependencies later:
 ```bash
 brew bundle --file="$(chezmoi source-path ~/.brewfile)"
 ```
+
+### Hover window focus on macOS
+
+AutoRaise focuses and brings a window to the front after a short hover, without
+moving the cursor. Its settings are managed in `~/.config/AutoRaise/config`.
+
+After installing dependencies and applying the dotfiles, enable it at login:
+
+```bash
+brew services start dimentium/autoraise/autoraise
+```
+
+Grant AutoRaise access in **System Settings → Privacy & Security → Accessibility**.
+If it is not listed, use **+**, press **Cmd+Shift+G**, and enter the path printed by
+`echo "$(brew --prefix autoraise)/bin/AutoRaise"`. Then restart it with
+`brew services restart dimentium/autoraise/autoraise`.
+
+Hold **Control** to temporarily suspend hover focus. To turn it off entirely:
+
+```bash
+brew services stop dimentium/autoraise/autoraise
+```
diff --git a/home/.chezmoiignore b/home/.chezmoiignore
index 08f015a..d54b12d 100644
--- a/home/.chezmoiignore
+++ b/home/.chezmoiignore
@@ -53,4 +53,5 @@ bin/video/cr3todng.sh
 
 {{ if ne .chezmoi.os "darwin" -}}
 .config/karabiner
+.config/AutoRaise
 {{ end -}}
diff --git a/home/dot_Brewfile b/home/dot_Brewfile
index 1046843..408770b 100644
--- a/home/dot_Brewfile
+++ b/home/dot_Brewfile
@@ -16,6 +16,10 @@ cask "brave-browser"
 cask "alacritty"
 cask "font-inconsolata"
 
+# Focus and raise windows when hovering
+tap "dimentium/autoraise"
+brew "dimentium/autoraise/autoraise"
+
 # Optional tools for audio conversion and local AI
 # brew "ffmpeg"
 # brew "ollama"
diff --git a/home/dot_config/AutoRaise/config b/home/dot_config/AutoRaise/config
new file mode 100644
index 0000000..2ffebf4
--- /dev/null
+++ b/home/dot_config/AutoRaise/config
@@ -0,0 +1,10 @@
+# Focus and raise after briefly hovering a window; never warp the cursor.
+pollMillis=50
+delay=4
+requireMouseStop=true
+warpX=0
+warpY=0
+# Hold Control to temporarily suspend hover focus.
+disableKey=control
+# Do not steal focus during authentication or screenshot selection.
+stayFocusedBundleIds="com.apple.SecurityAgent,com.apple.screencaptureui"