# stackline draws the window stacks that yabai leaves invisible

> stackline is a small Lua module for Hammerspoon that adds overlay indicators to yabai window stacks on macOS, since yabai's stacking feature ships without any interface of its own. It works, but the project has been quiet for years and needs a fork to keep going.

**AdamWagner/stackline** — Visualize yabai window stacks on macOS. Works with yabai & hammerspoon.

- Repository: https://github.com/AdamWagner/stackline
- Stars: 1,055 · Forks: 59
- Language: Lua
- License: not declared
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/adamwagner-stackline

## yabai stacks have no interface of their own

Stacking arrived in yabai in June 2020, and it created a blind spot. A stack lets several macOS windows occupy the same screen area and behave as a single unit, but nothing in the tiling window manager shows you which windows are hiding under the visible one. The project documentation is blunt about the consequence: there is no built-in UI for stacks, which makes it easy to forget about stacked windows that are not visible, and easy to get disoriented. stackline exists to fill that gap with unobtrusive visual indicators. It targets a specific audience: people who already run yabai as a tiling window manager and Hammerspoon as an automation host. If you run neither, there is nothing here to install, because stackline reads live window state from yabai and draws its overlays through the Hammerspoon API. It is a companion, not a window manager.

## The query layer stopped shelling out to yabai

stackline replaces nothing in yabai. yabai still owns the layout and the stack, and stackline observes it and reacts. The repository layout shows the code split into stackline/stackline.lua, stackmanager.lua, stack.lua, window.lua, query.lua and configmanager.lua, with a lib directory for bundled dependencies and a top-level conf.lua for configuration. The interesting part is the query layer, and the June 2021 changelog explains how it changed. The external dependency on jq was removed, the shell script used to call out to yabai was removed, and the third-party JSON library was replaced with hs.json. The same entry records a fix for a failure to parse JSON output from yabai that contains inf values, which the changelog notes might fix an older issue. Removing the shell out and the jq parsing means the data path now runs entirely inside Hammerspoon, and infinite values in yabai output used to be a hard stop for it.

## Cloning into ~/.hammerspoon and appending two lines to init.lua

Installation is a clone plus two appended lines. The project expects the source to live at ~/.hammerspoon/stackline so that Hammerspoon can require it as a module. The commands are:

```bash
git clone https://github.com/AdamWagner/stackline.git ~/.hammerspoon/stackline

cd ~/.hammerspoon
echo 'stackline = require "stackline"' >> init.lua
echo 'stackline:init()' >> init.lua
```

The first echo binds the module to a global named stackline, and the second calls its init function when Hammerspoon starts. After this, the directory should look like this:

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

Note that the repository root also contains an init.lua of its own, separate from the one in your ~/.hammerspoon directory. The wiki page for installing dependencies holds the remaining setup, including example keybindings for creating and navigating between stacks, which the repository page does not reproduce.

## Changing appearance.showIcons through the hs cli

Control happens over two channels: a shell command or direct access to the running instance from Hammerspoon. The optional part is the Hammerspoon cli tool, installed from the Hammerspoon console by typing hs.ipc.cliInstall() and hitting return. On Apple Silicon installations via Brew, the console call needs the Homebrew prefix passed in, hs.ipc.cliInstall("/opt/homebrew"), because the default path does not match where the binary lands. Once installed, confirm the binary is on your path:

```bash
which hs
```

After that you can flip settings from any terminal or script. Turning the app icons off, which switches the overlay to the slimmer indicators:

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

The same toggle is written with the other quoting style in the project documentation, using double quotes outside and single quotes inside. Both forms address the same config key, appearance.showIcons, in the configuration manager. Without the cli tool you can still call the same toggle from the Hammerspoon console, but scripted changes are what the cli is for.

## Indicators hug the window edge nearest the screen edge

The overlay is deliberately minimal. Two visual modes are offered: app icons that reveal which applications live inside a stack, and slim indicators that save space, toggled by the showIcons setting. Positioning is described as smart, with indicators staying on the outside edge of the window nearest the screen edge, so the indicator does not sit on top of the content you are trying to read. Multi-monitor support arrived in stackline v0.1.55, which matters because the edge rule has to be resolved per display rather than per screen. Two fixes in the 2021-06-06 release, tagged v0.1.61, went straight at the overlay's placement and state: offset indicators were corrected for the case where the menubar is not hidden, and icons now change when showIcons is toggled instead of keeping the previous drawing. The changelog also lives in a wiki page rather than in GitHub releases, and the repository has no GitHub releases at all.

## The author stopped working on it after Q3 2021

Maintenance is the central fact for anyone weighing this project. The project page states plainly that the author has not been able to work on it since Q3 2021, explaining that a bout of finger pain prevented typing for a stretch, and that the lesson taken was that a hobby should not require continuous typing. The same section says the author will not be working on it further, but that this does not prevent others from forking it and carrying the torch. The visible code movement is the last push, which was on 2026-04-17, though the repository records no GitHub releases and the most recent documented release is v0.1.61 from 2021-06-06. Treat 2026-04-17 as the date of the final code movement rather than evidence of a maintained project. The licence situation is also worth checking before you build on it: the README badge reads MIT, while the repository's own licence field is listed as unknown.

## Where stackline is the wrong tool

There are several cases where installing it is a mistake. It is macOS only and depends on two specific projects, yabai and Hammerspoon, so on Linux or on a plain macOS desktop it does nothing. It draws overlays, so it will conflict with setups that avoid any on-screen decoration, and it will misbehave around the menubar, which is exactly what the v0.1.61 offset fix addressed. If your memory of window layout is good enough, the indicators add a layer you did not ask for. The most consequential limitation is the maintenance one: with no release channel, no tagged versions, and the last code push on 2026-04-17 following a public end to development, any break in yabai's output format is yours to fix in a fork. The alternative approach is to use yabai's stacking with its own window navigation and no overlay at all, which is less visible but leaves you with no dependency to maintain. stackline's own answer is that the two are complementary rather than competing, and that forking is the intended path if you need changes.

## Conclusion

stackline fits a narrow and specific need: a macOS user who already runs yabai and Hammerspoon, wants stacks to be visible, and is willing to patch or fork a stalled project. It does not fit anyone who wants a supported, release-managed component, because there are no GitHub releases, the documented development stopped after Q3 2021, and the last push was on 2026-04-17 with no explanation of what changed. Before adopting it, verify that the yabai JSON that stackline parses still matches your installed yabai version, check that the 0.1.61 fixes for inf values and icon toggling still reproduce, and decide whether a Hammerspoon overlay fits your menu bar and multi-monitor setup.

## FAQ

### Does stackline work without yabai or Hammerspoon?

No. The stated prerequisites are yabai and Hammerspoon, and stackline is installed as a Hammerspoon module under ~/.hammerspoon/stackline. Without both, there is no window state to read and no surface to draw on.

### How do I turn the app icons off in stackline?

Toggle the appearance.showIcons setting, either from the Hammerspoon console or from a terminal through the cli tool with hs -c 'stackline.config:toggle("appearance.showIcons")'. The 2021-06-06 release fixed the case where icons did not change when this setting was toggled.

### Is stackline still being updated?

Not in any published release sense. The author states that work stopped after Q3 2021, the last documented release is v0.1.61 from 2021-06-06, the repository has no GitHub releases, and the last push was on 2026-04-17.

## Sources

- [AdamWagner/stackline on GitHub](https://github.com/AdamWagner/stackline)
- [Issues](https://github.com/AdamWagner/stackline/issues)
- [README](https://github.com/AdamWagner/stackline/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/adamwagner-stackline