Visualize yabai window stacks on macOS. Works with yabai & hammerspoon.
Latest update
See changes in more detail in the changelog.
Up next
You can find all the info below and more in the wiki.
What is stackline & why would I want to use it?
stackline adds 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…
- add & remove windows from a stack
- navigate between stacked windows
- understand the contents of a stack at a glance
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, yabai does 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 yabai window stacks.
Features
🚦 See your stacks. Window indicators show you which BSP leaves are stacks & how many windows each stack contains🔦 App icons. Toggle icons on to know exactly which apps are stacked where. Toggle icons off and get a slim minimalistic indicator that doesn't get in the way.🧘♂️ ️ Smart positioning. Whichever mode you prefer, indicators always stay out of the way on the outside edge of the window (nearest the screen edge).stackline v0.1.55has full support for multi-monitor setups, too.🧮 Always in sync. stackline keeps track of stacks as you move between spaces, resize windows, and add or remove stacks.🕹️ Flexible control. Control stackline via shell commands, or access the instance directly via Hammerspoon.
| Icon indicators… | …or minimal indicators |
|---|---|
|
|
Getting started with stackline
Prerequisites
- https://github.com/koekeishiya/yabai (install guide)
- https://github.com/Hammerspoon/hammerspoon (getting started guide)
- https://github.com/stedolan/jq (
brew install jq)
See wiki for example keybindings to create and navigate between stacks.
Installing stackline
1. Clone the repo into ~/.hammerspoon/stackline
# Get the repo git clone https://github.com/AdamWagner/stackline.git ~/.hammerspoon/stackline # Make stackline run when hammerspoon launches cd ~/.hammerspoon echo 'stackline = require "stackline.stackline.stackline"' >> init.lua echo 'stackline:init()' >> init.lua
Now your ~/.hammerspoon directory 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
└── …
2. Install the hammerspoon cli tool
- Ensure Hammerspoon is running
- Open the hammerspoon console via the menu bar
- Type
hs.ipc.cliInstall()and hit return
| Open the Hammperspoon console via the menu bar | Type `hs.ipc.cliInstall()` and hit return |
|---|---|
|
|
Finally confirm that hs is now available by entering the following in your terminal (shell):
❯ which hs /usr/local/bin/hs
RETRO? GO! FIDO? GO! GUIDANCE…
We're almost there!
# Launch yabai (or make sure it's running) brew services start yabai # Launch 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!.
Help us get to v1.0.0!
Give a
Thanks to contributors!
All are welcome (actually, please help us,
@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.
…on the shoulders of giants
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.
License & attribution
stackline is licensed under the
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