Skip to content
Switch branches/tags
Go to file


Failed to load latest commit information.
Latest commit message
Commit time
Nov 3, 2018


Hackable Hammerspoon Tiling WM

HHTWM is a module for Hammerspoon providing automatic layout-based tiling for macOS.

It's configurable, hackable, and composes well with other Hammerspoon libraries.


  1. install required dependency - hs._asm.undocumented.spaces
  2. copy hhtwm/ folder to ~/.hammerspoon/
  3. require the library in your init.lua:
hhtwm = require('hhtwm') -- it's recommended to make `hhtwm` a global object so it's not garbage collected.


Smallest init.lua that tiles by default (with no keybindings and no margins):

hhtwm = require('hhtwm')


All settings are optional.

  • hhtwm.margin - [number] - gap size between windows (in px)
  • hhtwm.screenMargin - [object] ({ top = 30, bottom = 5, left = 5, right = 5 }) - gap size from screen edges
  • hhtwm.defaultLayout - [string] - name of default layout to be applied
  • hhtwm.enabledLayouts - [array] - list of enabled layouts, all layouts are enabled by default
  • hhtwm.displayLayouts - [object] ({ [leftScreenId] = "equal-right" }) - per-screen default layouts
  • hhtwm.filters - [object] - filters to force tiling on/off, example:
    hhtwm.filters = {
      { app = 'Finder', tile = false } -- don't tile Finder
      { app = 'Hammerspoon', title = 'Hammerspoon Console', tile = true } -- force tile Hammerspoon Console
  • hhtwm.calcResizeStep - [function] - function to calculate resize step, example:
    hhtwm.calcResizeStep = function(screen)
      return 1 / hs.grid.getGrid(screen).w -- make the resize step be the same as hs.grid size for given screen


Module related

  • hhtwm.start() - starts watching for window changes and tiles when needed
  • hhtwm.stop() - stops hhtwm and stores current state in hs.settings, hhtwm.start() picks those settings up, so state can be persisted over reloads
  • hhtwm.tile() - force tile, usually not needed
  • hhtwm.reset() - reset hhtwm state, usually not needed

Window related

  • hhtwm.swapInDirection(win, dir) - swaps window in given direction if possible (direction: "west", "south", "north", "east")
  • hhtwm.throwToScreen(win, dir) - throws window to another screen in given direction
  • hhtwm.throwToScreenUsingSpaces(win, dir) - same as above but uses hs._asm.undocumented.spaces api
  • hhtwm.throwToSpace(win, spaceIndex) - throws window to space by given index
  • hhtwm.isFloating(win) - test if window is tiling/floating, returns true/false
  • hhtwm.toggleFloat(win) - toggles floating state of given window

Layout related

  • hhtwm.setLayout(layout) - sets layout for current space
  • hhtwm.getLayout() - gets layout for current space (returns layout name)
  • hhtwm.getLayouts() - returns list of available layouts (either hhtwm.enabledLayouts or all layouts from hhtwm)
  • hhtwm.resizeLayout(resizeOption) - resizes layout by given option, right now some layouts allow thinner/wider options
  • hhtwm.equalizeLayout() - resets the layout resize (usually to 50/50)

Example config

You can check out my usage of hhtwm in my dotfiles repo, although it might be over-engineered in places.


hackable tiling window manager for macOS and Hammerspoon




No releases published


No packages published