Visualize yabai window stacks on macOS. Works with yabai & hammerspoon.

Current status

Unfortunately, I've haven't been able to work on this project since Q3 2021. Initially, this was due to a scary bout of RSI-esque finger pain that entirely prevented from me from typing (really – I had to use Talon for basic computer use); The lesson I took away is that my hobbies shouldn't invovlve continuous typing (given I'm already typing all day for work).

I apologize that I won't be working on this anymore – but that doesn't mean you can't fork & carry the torch ;)

June 2021 update

2021-06-06: Fixes & cleanup (v0.1.61)

• Fixed: offset indicators when menubar is not hidden (#80)
• Fixed: Icons don't change when toggling showIcons (#68)
• Fixed: Failure to parse json output from yabai that contains inf values (might fix #46)
• Removed external dependency on jq
• Removed shell script used to call out to yabai
• Replaced third-party json library with hs.json
• Refactored unnecessary object-orientation out of stackline.query
• Cleaned up stackline.lib.utils

See changelog.

Everything below & more is in the wiki.

What is stackline & why would I want to use it?

stackline adds unobtrusive visual indicators to complement yabai's window stacking functionality.

A 'stack' enables multiple macOS windows to occupy the same screen space and behave as a single unit.

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, there's no built-in UI for stacks, which makes it easy to forget about stacked windows that aren't visible or get disoriented.

Enter stackline: unobtrusive visual indicators that complement yabai window stacks.

Features

• 🚦 Window indicators show the position and window count of stacks
• 🔦 Use app icons to show apps inside stacks or slim indicators to save space
• 🧘 Smart positioning. Indicators stay on the outside edge of the window nearest the screen edge
• 🕹️ Flexible control. Control stackline via shell commands, or access the instance directly via hammerspoon.
• 🖥️ Multi-monitor support introduced in stackline v0.1.55

Icon indicators…	…or minimal indicators

Quickstart

Prerequisites

• https://github.com/koekeishiya/yabai (install guide)
• https://github.com/Hammerspoon/hammerspoon (getting started guide)

See wiki for example keybindings to create and navigate between stacks.

Installation

1. Clone the repo into ~/.hammerspoon/stackline
2. Install the hammerspoon cli tool

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"' >> init.lua
echo 'stackline:init()' >> init.lua

Apple Silicon Users: you need to manually specify the path to yabai, because homebrew switched to installing packages into /opt/homebrew by default. You can set the path by replacing the stackline:init in your ~/.hammerspoon/init.lua:

stackline:init({
  paths = {
    yabai = "/opt/homebrew/bin/yabai"
  }
})

Now your ~/.hammerspoon directory should look like this:

├── init.lua
└── stackline
  ├── conf.lua
  ├── stackline
  │   ├── configmanager.lua
  │   ├── query.lua
  │   ├── stack.lua
  │   ├── stackline.lua
  │   ├── stackmanager.lua
  │   └── window.lua
  └── lib
      └── …

2. Install the hammerspoon cli tool

This is an optional step. It's required to send configuration commands to stackline from scripts, for example:

# Toggle boolean values with the hs cli
hs -c "stackline.config:toggle('appearance.showIcons')"

1. Ensure Hammerspoon is running

2. Open the hammerspoon console via the menu bar

3. Type hs.ipc.cliInstall() and hit return

   If Hammerspoon is installed via Brew on Apple Silicon, hs.ipc.cliInstall("/opt/homebrew") #2930

4. Confirm that hs is available by entering the following in your terminal (shell):

❯ which hs
/usr/local/bin/hs

Open the Hammperspoon console via the menu bar	Type `hs.ipc.cliInstall()` and hit return

Usage

• Launch yabai (or make sure it's running) (brew services start yabai)
• Launch hammerspoon (or make sure it's running) (open -a "Hammerspoon")

Create a window stack

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 your browser 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:

You can toggle minimalist mode by turning the icons off:

hs -c 'stackline.config:toggle("appearance.showIcons")'

See the wiki to for details about how to do this with a key binding.

Thanks to contributors!

All are welcome. 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 of 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.

Give a ⭐️ if you think (a more fully-featured version of) stackline would be useful!

…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 libraries 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 the 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