{"id":13477431,"url":"https://github.com/AdamWagner/stackline","last_synced_at":"2025-03-27T05:31:43.038Z","repository":{"id":41484452,"uuid":"284056365","full_name":"AdamWagner/stackline","owner":"AdamWagner","description":"Visualize yabai window stacks on macOS. Works with yabai \u0026 hammerspoon.","archived":false,"fork":false,"pushed_at":"2023-07-24T18:22:41.000Z","size":8067,"stargazers_count":956,"open_issues_count":37,"forks_count":47,"subscribers_count":14,"default_branch":"main","last_synced_at":"2024-10-30T10:49:03.345Z","etag":null,"topics":["hammerspoon","stacks","tabbed-layout","window-manager","yabai"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AdamWagner.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2020-07-31T14:32:04.000Z","updated_at":"2024-10-27T14:58:01.000Z","dependencies_parsed_at":"2024-02-18T03:42:51.645Z","dependency_job_id":null,"html_url":"https://github.com/AdamWagner/stackline","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdamWagner%2Fstackline","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdamWagner%2Fstackline/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdamWagner%2Fstackline/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AdamWagner%2Fstackline/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AdamWagner","download_url":"https://codeload.github.com/AdamWagner/stackline/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245791636,"owners_count":20672666,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hammerspoon","stacks","tabbed-layout","window-manager","yabai"],"created_at":"2024-07-31T16:01:42.687Z","updated_at":"2025-03-27T05:31:42.677Z","avatar_url":"https://github.com/AdamWagner.png","language":"Lua","funding_links":[],"categories":["Lua"],"sub_categories":[],"readme":"\u003c!-- vim: set tw=0 :--\u003e\n![stackline-logo](https://user-images.githubusercontent.com/1683979/90966915-1f9b1400-e48d-11ea-8cbb-0ceea6fcfc39.png)\n\u003cp\u003e\n  \u003cimg alt=\"Version\" src=\"https://img.shields.io/badge/version-0.1.61-blue.svg?cacheSeconds=2592000\" /\u003e\n  \u003ca href=\"#\" target=\"_blank\"\u003e\n    \u003cimg alt=\"License: MIT\" src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003e Visualize yabai window stacks on macOS. Works with yabai \u0026 hammerspoon.\n\n**Current status**\n\nUnfortunately, 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](https://talonvoice.com/) 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). \n\nI apologize that I won't be working on this anymore – but that doesn't mean _you_ can't fork \u0026 carry the torch ;) \n\n**June 2021 update**\n\n2021-06-06: Fixes \u0026 cleanup (`v0.1.61`)\n\n- Fixed: offset indicators when menubar is not hidden (#80)\n- Fixed: Icons don't change when toggling showIcons (#68)\n- Fixed: Failure to parse json output from `yabai` that contains `inf` values (might fix #46)\n- Removed external dependency on `jq`\n- Removed shell script used to call out to `yabai`\n- Replaced third-party json library with `hs.json`\n- Refactored unnecessary object-orientation out of `stackline.query`\n- Cleaned up `stackline.lib.utils`\n\nSee [changelog](https://github.com/AdamWagner/stackline/wiki/Changelog).\n\nEverything below \u0026 more is in the [wiki](https://github.com/AdamWagner/stackline/wiki/Install-dependencies).\n\n## What is stackline \u0026 why would I want to use it?\n\n`stackline` adds unobtrusive visual indicators to complement `yabai`'s window stacking functionality.\n\nA 'stack' enables multiple macOS windows to occupy the same screen space and behave as a single unit. \n\nStacks are a recent addition (June 2020) to the (_excellent!_) macOS tiling window manager [koekeishiya/yabai](https://github.com/koekeishiya/yabai). See [yabai #203](https://github.com/koekeishiya/yabai/issues/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.\n\nEnter `stackline`: unobtrusive visual indicators that complement `yabai` window stacks.\n\n![stackline-demo](https://user-images.githubusercontent.com/1683979/90967233-08f6bc00-e491-11ea-9b0a-d75f248ce4b1.gif)\n\n### Features\n\n- 🚦 **Window indicators** show the position and window count of stacks\n- 🔦 Use **app icons** to show apps inside stacks or slim indicators to save space\n- 🧘 **Smart positioning**. Indicators stay on the outside edge of the window nearest the screen edge\n- 🕹️ **Flexible control**. Control stackline via shell commands, or access the instance directly via hammerspoon.\n- 🖥️ **Multi-monitor support** introduced in `stackline v0.1.55`\n\n\u003ctable\u003e\n\u003ctbody\u003e\n\u003cthead\u003e\n \u003cth\u003eIcon indicators…\u003c/th\u003e\n \u003cth\u003e…or minimal indicators\u003c/th\u003e\n\u003c/thead\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\n       \u003cimg src=\"https://user-images.githubusercontent.com/1683979/90966909-1ad66000-e48d-11ea-9f64-7708a9e1d149.png\"/\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n       \u003cimg src=\"https://user-images.githubusercontent.com/1683979/90966912-1dd15080-e48d-11ea-9890-3e10ea7ce397.png\"/\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\n\n\n## Quickstart\n\n### Prerequisites\n\n- https://github.com/koekeishiya/yabai ([install guide](https://github.com/koekeishiya/yabai/wiki/Installing-yabai-(latest-release)))\n- https://github.com/Hammerspoon/hammerspoon ([getting started guide](https://www.hammerspoon.org/go/))\n\nSee [wiki](https://github.com/AdamWagner/stackline/wiki/Install-\u0026-configure-dependencies#user-content-configure-yabai-stacks) for example keybindings to create and navigate between stacks.\n\n### Installation\n\n1. [Clone the repo into ~/.hammerspoon/stackline](https://github.com/AdamWagner/stackline/wiki/Install-stackline#1-clone-the-repo-into-hammerspoonstackline)\n2. [Install the hammerspoon cli tool](https://github.com/AdamWagner/stackline/wiki/Install-stackline#2-install-the-hammerspoon-cli-tool)\n\n#### 1. Clone the repo into ~/.hammerspoon/stackline\n\n```sh\n# Get the repo\ngit clone https://github.com/AdamWagner/stackline.git ~/.hammerspoon/stackline\n\n# Make stackline run when hammerspoon launches\ncd ~/.hammerspoon\necho 'stackline = require \"stackline\"' \u003e\u003e init.lua\necho 'stackline:init()' \u003e\u003e init.lua\n```\n\nNow your `~/.hammerspoon` directory should look like this:\n\n```\n├── init.lua\n└── stackline\n  ├── conf.lua\n  ├── stackline\n  │   ├── configmanager.lua\n  │   ├── query.lua\n  │   ├── stack.lua\n  │   ├── stackline.lua\n  │   ├── stackmanager.lua\n  │   └── window.lua\n  └── lib\n      └── …\n```\n\n\n#### 2. Install the hammerspoon cli tool\n\nThis is an optional step. It's required to send configuration commands to `stackline` from scripts, for example:\n\n```sh\n# Toggle boolean values with the hs cli\nhs -c \"stackline.config:toggle('appearance.showIcons')\"\n```\n1. Ensure Hammerspoon is running\n2. Open the hammerspoon console via the menu bar\n3. Type `hs.ipc.cliInstall()` and hit return\n                          \n    If Hammerspoon is installed via Brew on Apple Silicon, `hs.ipc.cliInstall(\"/opt/homebrew\")` [#2930](https://github.com/Hammerspoon/hammerspoon/issues/2930)\n4. Confirm that `hs` is available by entering the following in your terminal (shell):\n\n```sh\n❯ which hs\n/usr/local/bin/hs\n```\n\n\u003ctable\u003e\n\u003ctbody\u003e\n\u003cthead\u003e\n \u003cth\u003eOpen the Hammperspoon console via the menu bar\u003c/th\u003e\n \u003cth\u003eType `hs.ipc.cliInstall()` and hit return\u003c/th\u003e\n\u003c/thead\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\n       \u003cimg src=\"https://user-images.githubusercontent.com/1683979/90970190-66513400-e4b6-11ea-9385-6e31571fd013.png\"/\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n       \u003cimg src=\"https://user-images.githubusercontent.com/1683979/100528318-769d3d00-3190-11eb-8444-1a70ad5f7baa.png\"/\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\n\n### Usage\n\n- Launch `yabai` (or make sure it's running) (`brew services start yabai`)\n- Launch `hammerspoon` (or make sure it's running) (`open -a \"Hammerspoon\"`)\n\n**Create a window stack**\n\nNow, 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](https://github.com/AdamWagner/stackline/wiki/Install-dependencies)) to create a stack:\n\n```sh\nyabai -m window --stack next\n```\n\nDid 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:\n\n\u003cimg width=\"50%\" src=\"https://user-images.githubusercontent.com/1683979/90969027-53376780-e4a8-11ea-88c9-354f43b0a4ef.png\" /\u003e\n\nYou can toggle minimalist mode by turning the icons off:\n\n```sh\nhs -c 'stackline.config:toggle(\"appearance.showIcons\")'\n```\n\n\u003cimg width=\"50%\" src=\"https://user-images.githubusercontent.com/1683979/90969026-52063a80-e4a8-11ea-885d-9dd5b1409f20.png\" /\u003e\n\nSee the wiki to [for details about how to do this with a key binding](https://github.com/AdamWagner/stackline/wiki/Keybindings).\n\n\n## Thanks to contributors!\n\nAll are welcome. Feel free to dive in by opening an [issue](https://github.com/AdamWagner/stackline/issues/new) or submitting a PR.\n\n[@alin23](https://github.com/alin23) initially proposed the [concept for stackline here](https://github.com/koekeishiya/yabai/issues/203#issuecomment-652948362) and encouraged [@AdamWagner](https://github.com/AdamWagner) to share the mostly-broken proof-of-concept publicly. Since then, [@alin23](https://github.com/alin23) dramatically improved upon the initial proof-of-concept with [#13](https://github.com/AdamWagner/stackline/pull/13), has some pretty whiz-bang functionality on deck with [#17](https://github.com/AdamWagner/stackline/pull/17), and has been a great thought partner/reviewer.  \n\n[@zweck](https://github.com/zweck), who, [in the same thread](https://github.com/koekeishiya/yabai/issues/203#issuecomment-656780281), got the gears turning about how [@alin23](https://github.com/alin23)'s idea could be implemented and _also_ urged Adam to share his POC.\n\n[@johnallen3d](https://github.com/johnallen3d) for being of one the first folks to install stackline, and for identifying several mistakes \u0026 gaps in the setup instructions. \n\n[@pete-may](https://github.com/pete-may) for saving folks from frustration by fixing an out-of-date command in the readme ([#48](https://github.com/AdamWagner/stackline/pull/48))\n\n[@AdamWagner](https://github.com/AdamWagner) wrote the initial proof-of-concept (POC) for stackline.\n\nGive a ⭐️ if you think (a more fully-featured version of) stackline would be useful!\n\n### …on the shoulders of giants\n\nThanks to [@koekeishiya](https://github.com/koekeishiya) without whom the _wonderful_ [yabai](https://github.com/koekeishiya/yabai) would not exist, and projects like this would have no reason to exist.\n\nSimilarly, thanks to [@dominiklohmann](https://github.com/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.\n\nThanks to [@cmsj](https://github.com/cmsj), [@asmagill](https://github.com/asmagill), and all of the contributors to [hammerspoon](https://github.com/Hammerspoon/hammerspoon) for making macos APIs accessible to the rest of us!\n\nThanks to the creators \u0026 maintainers of the lua utility libraries [underscore.lua](https://github.com/mirven/underscore.lua), [lume.lua](https://github.com/rxi/lume), and [self.lua](https://github.com/M1que4s/self).\n\n## License \u0026 attribution\n\nstackline is licensed under the [\u0026nearr;\u0026nbsp;MIT\u0026nbsp;License](stackline-license), the same license used by [yabai](https://github.com/koekeishiya/yabai/blob/master/LICENSE.txt) and [hammerspoon](https://github.com/Hammerspoon/hammerspoon/blob/master/LICENSE).\n\nMIT 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.\n\n[MIT](LICENSE) © Adam Wagner\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAdamWagner%2Fstackline","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAdamWagner%2Fstackline","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAdamWagner%2Fstackline/lists"}