tarmac
A tiling window manager for macOS. BSP layout, Lua configuration, IPC control.
macOS Tahoe (15.0+), Apple Silicon.
Install
brew install gardesk/tap/tarmac
Or build from source:
git clone --recurse-submodules git@github.com:gardesk/tarmac.git
cd tarmac
cargo build --release
Binaries land in target/release/ — tarmac, tarmacctl, and ers (border renderer).
Usage
tarmac # start the window manager
tarmacctl get-workspaces # query workspace state
tarmacctl focus left # focus window to the left
tarmacctl subscribe # stream events (JSON)
Requires Accessibility permission: System Settings > Privacy & Security > Accessibility.
Configuration
~/.config/tarmac/init.lua — created on first run.
gar.set("mod_key", "option")
gar.set("gap_inner", 8)
gar.set("gap_outer", 8)
gar.set("border_width", 4)
gar.bind("mod+h", "focus left")
gar.bind("mod+shift+h", "swap left")
gar.bind("mod+1", "workspace 1")
gar.rule({ app_name = "Calculator" }, { floating = true })
gar.on("workspace_changed", function(old, new)
gar.exec("sketchybar --trigger tarmac_wkspc")
end)
Hot reload: Mod+Shift+R
What it does
- BSP tiling with automatic split direction
- 10 numbered workspaces + scratchpads
- Multi-monitor with per-monitor workspaces
- Focus-follows-mouse, mouse-follows-focus
- Window rules (auto-float, workspace assignment)
- Window borders via ers (SkyLight overlays)
- IPC over Unix socket (JSON protocol)
- Lua event callbacks
What it doesn't do
- No Wayland/Linux support — macOS only, uses private SkyLight framework
- No window animations
- No built-in bar — integrates with sketchybar or similar via IPC/callbacks
- Multi-monitor support has known rough edges (see docs)
Documentation
tarmac.musicsian.com — configuration reference, keybindings, IPC protocol, window rules, troubleshooting.
License
MIT
View source
| 1 | # tarmac |
| 2 | |
| 3 | A tiling window manager for macOS. BSP layout, Lua configuration, IPC control. |
| 4 | |
| 5 | macOS Tahoe (15.0+), Apple Silicon. |
| 6 | |
| 7 | ## Install |
| 8 | |
| 9 | ```bash |
| 10 | brew install gardesk/tap/tarmac |
| 11 | ``` |
| 12 | |
| 13 | Or build from source: |
| 14 | |
| 15 | ```bash |
| 16 | git clone --recurse-submodules git@github.com:gardesk/tarmac.git |
| 17 | cd tarmac |
| 18 | cargo build --release |
| 19 | ``` |
| 20 | |
| 21 | Binaries land in `target/release/` — `tarmac`, `tarmacctl`, and `ers` (border renderer). |
| 22 | |
| 23 | ## Usage |
| 24 | |
| 25 | ```bash |
| 26 | tarmac # start the window manager |
| 27 | tarmacctl get-workspaces # query workspace state |
| 28 | tarmacctl focus left # focus window to the left |
| 29 | tarmacctl subscribe # stream events (JSON) |
| 30 | ``` |
| 31 | |
| 32 | Requires Accessibility permission: System Settings > Privacy & Security > Accessibility. |
| 33 | |
| 34 | ## Configuration |
| 35 | |
| 36 | `~/.config/tarmac/init.lua` — created on first run. |
| 37 | |
| 38 | ```lua |
| 39 | gar.set("mod_key", "option") |
| 40 | gar.set("gap_inner", 8) |
| 41 | gar.set("gap_outer", 8) |
| 42 | gar.set("border_width", 4) |
| 43 | |
| 44 | gar.bind("mod+h", "focus left") |
| 45 | gar.bind("mod+shift+h", "swap left") |
| 46 | gar.bind("mod+1", "workspace 1") |
| 47 | |
| 48 | gar.rule({ app_name = "Calculator" }, { floating = true }) |
| 49 | gar.on("workspace_changed", function(old, new) |
| 50 | gar.exec("sketchybar --trigger tarmac_wkspc") |
| 51 | end) |
| 52 | ``` |
| 53 | |
| 54 | Hot reload: `Mod+Shift+R` |
| 55 | |
| 56 | ## What it does |
| 57 | |
| 58 | - BSP tiling with automatic split direction |
| 59 | - 10 numbered workspaces + scratchpads |
| 60 | - Multi-monitor with per-monitor workspaces |
| 61 | - Focus-follows-mouse, mouse-follows-focus |
| 62 | - Window rules (auto-float, workspace assignment) |
| 63 | - Window borders via ers (SkyLight overlays) |
| 64 | - IPC over Unix socket (JSON protocol) |
| 65 | - Lua event callbacks |
| 66 | |
| 67 | ## What it doesn't do |
| 68 | |
| 69 | - No Wayland/Linux support — macOS only, uses private SkyLight framework |
| 70 | - No window animations |
| 71 | - No built-in bar — integrates with sketchybar or similar via IPC/callbacks |
| 72 | - Multi-monitor support has known rough edges (see docs) |
| 73 | |
| 74 | ## Documentation |
| 75 | |
| 76 | **[tarmac.musicsian.com](https://tarmac.musicsian.com)** — configuration reference, keybindings, IPC protocol, window rules, troubleshooting. |
| 77 | |
| 78 | ## License |
| 79 | |
| 80 | MIT |