From af1d1634c2bfd705e2f5a15eea2c7c804fd264f2 Mon Sep 17 00:00:00 2001 From: WickedYoda <68271168+wickedyoda@users.noreply.github.com> Date: Tue, 11 Aug 2026 21:53:55 -0500 Subject: [PATCH] feat: add macOS window tiling script (Hammerspoon) (#91) - Tile two most-recent windows side by side on main screen - Includes Hammerspoon config, clickable AppleScript .app, and README - Fixes pre-existing merge conflict markers in mac-scripts READMEs Co-authored-by: Wicked Yoda --- mac-scripts/README.md | 34 ++--- mac-scripts/brewscripts/README.md | 25 +--- mac-scripts/tile-windows/README.md | 53 ++++++++ mac-scripts/tile-windows/hammerspoon-init.lua | 122 ++++++++++++++++++ .../tile-windows/tile-windows.applescript | 26 ++++ 5 files changed, 214 insertions(+), 46 deletions(-) create mode 100644 mac-scripts/tile-windows/README.md create mode 100644 mac-scripts/tile-windows/hammerspoon-init.lua create mode 100644 mac-scripts/tile-windows/tile-windows.applescript diff --git a/mac-scripts/README.md b/mac-scripts/README.md index 919df0d..379c2c1 100644 --- a/mac-scripts/README.md +++ b/mac-scripts/README.md @@ -1,31 +1,16 @@ -<<<<<<< HEAD - # mac-scripts - - ## Purpose - This directory contains files related to **mac scripts**. - - ## Contents - - `not working- download-sync.sh` -- `rsync basic.sh` -- `disable_DS_store.sh` - - ## Usage - - Review each script or configuration file before running - - Some scripts may require **root or sudo** - - Paths and variables may need adjustment for your environment - - ## Notes - - This folder is part of the **public-setupfiles** repository - - Files are provided as-is for reference or automation - - ## Safety - Always back up data before running scripts that modify system state. -======= # mac-scripts ## Overview This directory is part of the **public-setupfiles** repository. -It contains scripts, configuration files, or resources related to **mac-scripts**. +It contains scripts, configuration files, or resources related to **macOS**. + +## Contents +- `brewscripts/` – Homebrew package update and install helpers +- `disable_DS_store.sh` – Disable `.DS_Store` files on network volumes +- `DS_STore_destroy.sh` – Clean up existing `.DS_Store` files +- `system_updates.sh` – Update macOS and Homebrew +- `updates.sh` – General macOS update script +- `tile-windows/` – One-click window tiling script (Hammerspoon-based) ## Usage - Review scripts before execution @@ -41,4 +26,3 @@ Scripts may generate logs or output files in the same directory or system locati - Use at your own risk --- ->>>>>>> main diff --git a/mac-scripts/brewscripts/README.md b/mac-scripts/brewscripts/README.md index dd76467..042f8a3 100644 --- a/mac-scripts/brewscripts/README.md +++ b/mac-scripts/brewscripts/README.md @@ -1,27 +1,11 @@ # brewscripts -<<<<<<< HEAD -## Purpose -This directory contains files related to **brewscripts**. - -## Contents -- `update-brew-packages.sh` - -## Usage -- Review each script or configuration file before running -- Some scripts may require **root or sudo** -- Paths and variables may need adjustment for your environment - -## Notes -- This folder is part of the **public-setupfiles** repository -- Files are provided as-is for reference or automation - -## Safety -Always back up data before running scripts that modify system state. -======= ## Overview This directory is part of the **public-setupfiles** repository. -It contains scripts, configuration files, or resources related to **brewscripts**. +It contains scripts related to **Homebrew** package management on macOS. + +## Contents +- `update-brew-packages.sh` – Update Homebrew and upgrade installed packages ## Usage - Review scripts before execution @@ -37,4 +21,3 @@ Scripts may generate logs or output files in the same directory or system locati - Use at your own risk --- ->>>>>>> main diff --git a/mac-scripts/tile-windows/README.md b/mac-scripts/tile-windows/README.md new file mode 100644 index 0000000..1faece5 --- /dev/null +++ b/mac-scripts/tile-windows/README.md @@ -0,0 +1,53 @@ +# Tile Two Windows (macOS) + +Tiles the **current window** and the **previous window** side by side on the main screen with a single click (or `Cmd+Ctrl+T`). + +Uses [Hammerspoon](https://www.hammerspoon.org) for window management via the macOS Accessibility API. + +## Files + +| File | Purpose | +|---|---| +| `hammerspoon-init.lua` | Hammerspoon config with the tiling logic | +| `tile-windows.applescript` | Clickable `.app` source that triggers tiling via Hammerspoon IPC | + +## Setup (on your macOS machine) + +### 1. Install Hammerspoon +```bash +brew install --cask hammerspoon +``` +Open Hammerspoon and **grant Accessibility permission** in System Settings → Privacy & Security → Accessibility. + +### 2. Install the config +```bash +# Back up existing config if you have one +cp ~/.hammerspoon/init.lua ~/.hammerspoon/init.lua.bak 2>/dev/null + +# Copy our tiling config in +cp hammerspoon-init.lua ~/.hammerspoon/init.lua + +# Reload +hs -c "hs.reload()" +# OR: click the Hammerspoon menubar icon → Reload All +``` + +### 3. Enable IPC Server +- Hammerspoon → Preferences → check **"Enable CLI (IPC Server)"** +- This registers the `hs` command so the AppleScript can invoke it. + +### 4. (Optional) Build the clickable app +```bash +# From this directory: +osacompile -o ~/Applications/Tile\ Windows.app tile-windows.applescript +``` +Drag "Tile Windows.app" to your Dock. Clicking it tiles the two most-recent windows. + +## How it works + +- **Focus tracking**: Hammerspoon records every window focus event in a ring (up to 10 recent windows). +- **Tiling**: When triggered (hotkey or click), it grabs the two most-recently-focused *visible* windows and splits the main screen into two halves with a 6px gap between them. +- **Main screen**: Windows are always placed on the screen where the most-recent window currently lives (defaults to the main display). + +## Alternative: no .app needed +If you just want the keyboard shortcut `Cmd+Ctrl+T`, skip step 4 — the Hammerspoon config already binds it. diff --git a/mac-scripts/tile-windows/hammerspoon-init.lua b/mac-scripts/tile-windows/hammerspoon-init.lua new file mode 100644 index 0000000..bcf985c --- /dev/null +++ b/mac-scripts/tile-windows/hammerspoon-init.lua @@ -0,0 +1,122 @@ +--[[ + Hammerspoon config: Tile two most-recent windows side by side + on the main screen, activated by click or hotkey. + + Install: + 1. Install Hammerspoon: https://www.hammerspoon.org + 2. Copy this file to ~/.hammerspoon/init.lua (or merge) + 3. In Hammerspoon → Open Config Folder → Reload All + 4. Grant Accessibility permission to Hammerspoon in System Settings. + 5. (Optional) Assign hotkey: Cmd+Ctrl+T toggles tiling. + 6. Build the clickable .app from tile-windows.applescript (see companion file). +--]] + +-- Config --------------------------------------------------------------- +local HOTKEY = { "cmd", "ctrl" } +local HOTKEY_KEY = "t" + +-- Window focus-order tracking ------------------------------------------- +-- We keep a ring of recently-focused normal windows. When tiling, we grab +-- the two most recent distinct windows and place them side by side. +local focusOrder = {} +local MAX_HISTORY = 10 + +local function recordFocus(win) + if not win or not win:id() then return end + -- Remove any existing entry for this window, then push to front. + local filtered = {} + for _, w in ipairs(focusOrder) do + if w:id() ~= win:id() then + table.insert(filtered, w) + end + end + table.insert(filtered, win) + -- Trim oldest + if #filtered > MAX_HISTORY then + table.remove(filtered, 1) + end + focusOrder = filtered +end + +-- Track all app windows +local trackFilter = hs.windowFilter.new(nil, "TrackAll") +trackFilter:setWindowFilter("AXStandardWindow", true) +trackFilter:subscribe(hs.windowFilter.windowFocused, function(win) + recordFocus(win) +end) + +-- Core tiling function -------------------------------------------------- +local function tileTwoWindows() + -- Collect all currently-visible normal windows (skip minimized/invisible) + local allWins = hs.window.allWindows() + local visible = {} + for _, w in ipairs(allWins) do + local fr = w:frame() + if fr.w > 0 and fr.h > 0 then + table.insert(visible, w) + end + end + + if #visible < 2 then + hs.alert.show("Need 2+ visible windows") + return + end + + -- Prefer the two most-recently-focused visible windows. + local function focusIndex(win) + for i, w in ipairs(focusOrder) do + if w:id() == win:id() then return i end + end + return 9999 + end + table.sort(visible, function(a, b) + return focusIndex(a) < focusIndex(b) + end) + + local winA = visible[1] + local winB = visible[2] + + if not winA or not winB then + hs.alert.show("No windows to tile") + return + end + + -- Determine the screen for winA (its current screen, or main screen) + local screen = winA:screen() + if not screen then + screen = hs.screen.mainScreen() + end + local screenFrame = screen:frame() + + -- Compute two halves with a small gap + local gap = 6 + local halfW = (screenFrame.w - gap) / 2 + local halfH = screenFrame.h + + local frameA = hs.geometry.rect(screenFrame.x, screenFrame.y, halfW, halfH) + local frameB = hs.geometry.rect(screenFrame.x + halfW + gap, screenFrame.y, halfW, halfH) + + winA:setFrame(frameA) + winB:setFrame(frameB) + + -- Focus the first window + winA:focus() + + hs.alert.show("Tiled \xe2\x9c\x93") +end + +-- Hotkey binding +hs.hotkey.bind(HOTKEY, HOTKEY_KEY, tileTwoWindows) + +-- Expose for AppleScript / IPC: `hs -c 'tileTwoWindows()'` +_G.tileTwoWindows = tileTwoWindows + +-- Optional: menubar button for one-click trigger (alternative to .app) +local mb = hs.menubar.new(true, "TileClick") +mb:setTitle("\x.f\x87") +mb:setTooltip("Tile two recent windows") +mb:setClickCallback(function() + tileTwoWindows() +end) + +print("Hammerspoon tiling config loaded. Hotkey: Cmd+Ctrl+T. Menubar icon ready.") diff --git a/mac-scripts/tile-windows/tile-windows.applescript b/mac-scripts/tile-windows/tile-windows.applescript new file mode 100644 index 0000000..bb1e336 --- /dev/null +++ b/mac-scripts/tile-windows/tile-windows.applescript @@ -0,0 +1,26 @@ +-- tile-windows.applescript +-- A clickable macOS app that tells Hammerspoon to tile the two most-recent +-- windows side by side on the main screen. +-- +-- REQUIREMENTS: +-- 1. Hammerspoon must be installed and running (https://hammerspoon.org) +-- 2. This file's companion init.lua must be loaded in ~/.hammerspoon/init.lua +-- 3. In Hammerspoon → Preferences → "Enable CLI (IPC Server)" must be checked +-- (this registers the `hs` command on your PATH) +-- +-- BUILD INSTRUCTIONS (creates a double-clickable .app): +-- Open Script Editor.app → File → Open... navigate to this file. +-- Or use osacompile from Terminal: +-- osacompile -o ~/Applications/Tile\ Windows.app tile-windows.applescript +-- Then double-click "Tile Windows.app" in Finder/Dock to run it. + +try + set resultText to do shell script "/opt/homebrew/bin/hs -c 'tileTwoWindows()'" +on error errMsg number errNum + -- If the IPC call fails, fall back to a friendly notification + display notification "Could not reach Hammerspoon IPC. Make sure Hammerspoon is running and IPC Server is enabled." with title "Tile Windows" subtitle "❌" + return +end try + +-- Optional: brief visual confirmation +display notification "Windows tiled ✓" with title "Tile Windows"