stackline: A Lua repository from pete-may

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.

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.55 has 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

Open the hammerspoon console via the menu bar, type hs.ipc.cliInstall(), and hit return.

Confirm that hs is now available:

❯ 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:

 echo ":toggle_appearance.show_icons:" | hs -m stackline-config

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 ⭐️ if you think (a more fully-featured version of) stackline would be useful!

Thanks to contributors!

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.

@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 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.

pete-may/stackline