Configuring stackline

Configuring Stackline

There are 3 configuration themes:

Appearance Customize indicator sizing, coloring, positioning, roundness, animation durations, form factor, etc

Features Enable/disable fuzzy frame detection, click-to-focus, the hacky workaround for https://github.com/Hammerspoon/hammerspoon/issues/2400, or – coming soon – window titles. The ability to toggle features on/off means that you won't have to put up with bugs in a feature that you don't even use ;-)

Paths An easier way to specify paths to binaries & scripts without mucking around in the stackline source.

---

Config validation & live-tweaking

All config values can be edited while stackline is running (this should seem familiar from yabai).

Values can be set using the hs cli tool:

hs -c "stackline.config:set('appearance.radius', 3)"

… or the ipc port:

echo ":appearance.radius:3` | hs -m stackline-config

All config fields support get(key), set(key, val), and getOrSet(key, [val]). In addition, boolean fields support toggle()

You can get and set nested config fields via a dot-separated path, like this: features.fzyFrameDetection.enabled

Config fields are typed and validated on initialization and when live-set. stackline will notify you If you can't remember the exact path to a config variable:

---

The default config

c = {}
c.paths = {}
c.appearance = {}
c.features = {}
c.advanced = {}

-- Paths
c.paths.getStackIdxs                  = hs.configdir .. '/stackline/bin/yabai-get-stack-idx'
c.paths.jq                            = '/usr/local/bin/jq'
c.paths.yabai                         = '/usr/local/bin/yabai'

-- Appearance
c.appearance.color                    = { white = 0.90 }
c.appearance.alpha                    = 1
c.appearance.dimmer                   = 2.5                 -- larger numbers increase contrast b/n focused & unfocused state
c.appearance.iconDimmer               = 1.1                 -- Higher numbers dim inactive icons *less* than the non-icon indicators
c.appearance.showIcons                = true                -- Window indicator style ('lozenge'-shaped when false)
c.appearance.size                     = 32                  -- Size of window indicators (height when icons off)
c.appearance.radius                   = 3                   -- Indicator roundness. Higher numbers → *less* roundness… I'm sorry
c.appearance.iconPadding              = 4                   -- Space between icon & indicator edge. Higher numbers → smaller, more inset icons
c.appearance.pillThinness             = 6                   -- Aspect ratio of pill-style icons (width = size / pillThinness)

c.appearance.vertSpacing              = 1.2                 -- Amount of vertical space between indicators

c.appearance.offset                   = {}                  -- Offset controls position of stack indicators relative to the window
c.appearance.offset.y                 = 2                   -- Distance from top of the window to render indicators
c.appearance.offset.x                 = 4                   -- Distance away from the edge of the window to render indicators

c.appearance.shouldFade               = true                -- Enable/disable fade animations
c.appearance.fadeDuration             = 0.2                 -- Duration of fade animations (seconds) 

-- Features
c.features.clickToFocus               = true                -- Click indicator to focus window. Mouse clicks are tracked when enabled
c.features.hsBugWorkaround            = true                -- Workaround for https://github.com/Hammerspoon/hammerspoon/issues/2400

c.features.fzyFrameDetect             = {}                  -- Round window frame dimensions by fuzzFactor before identifying stacked windows
c.features.fzyFrameDetect.enabled     = true                -- Enable/disable fuzzy frame detection
c.features.fzyFrameDetect.fuzzFactor  = 30                  -- Window frame dimensions will be rounded to nearest fuzzFactor

c.features.winTitles                 = 'not_implemented'    -- Valid options: false, true, 'when_switching', 'not_implemented'
c.features.dynamicLuminosity         = 'not_implemented'    -- Valid options: false, true, 'not_implemented'

c.advanced.maxRefreshRate             = 0.3                 -- How aggressively to refresh Stackline. Higher = slower response time + less battery drain

return c

Next: Keybindings →