Visualize yabai window stacks on macOS. Works with yabai & hammerspoon.
Visualize yabai window stacks on macOS. Works with yabai & hammerspoon.
Latest update
📣 Update: improved configuration: please review docs for 💔️ breaking changes!
See changes in more detail in the changelog.
Up next
🛠️ In progress: Refactoring for testability → Unit tests
You can find all the info below and more in the wiki.
stacklineadds simple, unobtrusive visual indicators to compliment
yabai's window stacking functionality.
A 'stack' is a generalized subset of a tabbed UI that enables multiple macOS windows to occupy the same screen space and behave as a single unit. A stack let's a user…
Stacks are a recent addition (June 2020) to the (excellent!) macOS tiling window manager koekeishiya/yabai. See yabai #203 for more info about
yabai's stacking feature. Currently,
yabaidoes not provide visual indication of a stack's active window or the inactive windows below. This makes it easy to forgot about the stacked windows that aren't visible.
Enter
stackline: simple, unobtrusive visual indicators that compliment
yabaiwindow stacks.
stackline v0.1.55has full support for multi-monitor setups, too.
Icon indicators… | …or minimal indicators |
---|---|
![]() |
![]() |
brew install jq)
See wiki for example keybindings to create and navigate between stacks.
# Get the repo git clone https://github.com/AdamWagner/stackline.git ~/.hammerspoon/stacklineMake stackline run when hammerspoon launches
cd ~/.hammerspoon echo 'stackline = require "stackline.stackline.stackline"' >> init.lua echo 'stackline:init()' >> init.lua
Now your
~/.hammerspoondirectory should look like this:
├── init.lua └── stackline ├── bin │ └── yabai-get-stack-idx ├── conf.lua ├── stackline │ ├── configmanager.lua │ ├── query.lua │ ├── stack.lua │ ├── stackline.lua │ ├── stackmanager.lua │ └── window.lua └── lib └── …
hs.ipc.cliInstall()and hit return
Open the Hammperspoon console via the menu bar | Type `hs.ipc.cliInstall()` and hit return |
---|---|
![]() |
![]() |
Finally confirm that
hsis now available by entering the following in your terminal (shell):
❯ which hs /usr/local/bin/hs
We're almost there!
# Launch yabai (or make sure it's running) brew services start yabaiLaunch hammerspoon (or make sure it's running)
open -a "Hammerspoon"
Now, assuming you've been issuing these commands from a terminal and also have a browser window open on the same space, make sure your terminal is positioned immediately to the left of Safari and issue the following command (or use keybindings) to create a stack:
yabai -m window --stack next
Did the terminal window expand to cover the area previously occupied by Safari? Great! At this point, you should notice two app icons at the top-left corner of your terminal window, like this:
If the icons are a bit too heavy for you, you can toggle minimalist mode by turning the icons off:
hs -c 'stackline.config:toggle("appearance.showIcons")'
The minimalist stack indicator style is shown here ↑
See the wiki to for details about how to do this with a key binding!.
Give a ⭐️ if you think (a more fully-featured version of) stackline would be useful!
All are welcome (actually, please help us, 🤣️)! Feel free to dive in by opening an issue or submitting a PR.
@alin23 initially proposed the concept for stackline here and encouraged @AdamWagner to share the mostly-broken proof-of-concept publicly. Since then, @alin23 dramatically improved upon the initial proof-of-concept with #13, has some pretty whiz-bang functionality on deck with #17, and has been a great thought partner/reviewer.
@zweck, who, in the same thread, got the gears turning about how @alin23's idea could be implemented and also urged Adam to share his POC.
@johnallen3d for being one the first folks to install stackline, and for identifying several mistakes & gaps in the setup instructions.
@pete-may for saving folks from frustration by fixing an out-of-date command in the readme (#48)
@AdamWagner wrote the initial proof-of-concept (POC) for stackline.
Thanks to @koekeishiya without whom the wonderful yabai would not exist, and projects like this would have no reason to exist.
Similarly, thanks to @dominiklohmann, who has helped so many people make chunkwm/yabai "do the thing" they want and provides great feedback on new and proposed yabai features.
Thanks to @cmsj, @asmagill, and all of the contributors to hammerspoon for making macOS APIs accessible to the rest of us!
Thanks to the creators & maintainers of the lua utility libaries underscore.lua, lume.lua, and self.lua.
stackline is licensed under the ↗ MIT License, the same license used by yabai and hammerspoon.
MIT is a simple permissive license with conditions only requiring preservation of copyright and license notices. Licensed works, modifications, and larger works may be distributed under different terms and without source code.
MIT © Adam Wagner