Installation

Shoji runs on Hammerspoon, a macOS automation tool. This guide walks you through installing both, which only takes a few minutes.

Install Hammerspoon

Download from the official website or use Homebrew:

brew install hammerspoon --cask

After installation:

1. Launch Hammerspoon from Applications
2. Grant Accessibility permissions when prompted. Hammerspoon needs this to move and resize windows. (System Settings > Privacy & Security > Accessibility)
3. Confirm Hammerspoon appears in the menu bar

Install Shoji

Clone Shoji into the Hammerspoon Spoons directory:

git clone https://github.com/majjoha/Shoji.spoon \
  ~/.hammerspoon/Spoons/Shoji.spoon

Or download the latest ZIP and extract to ~/.hammerspoon/Spoons/Shoji.spoon.

Verify the installation

Add to ~/.hammerspoon/init.lua (create if needed):

hs.loadSpoon("Shoji")
print("Shoji loaded:", spoon.Shoji ~= nil)

Reload Hammerspoon from the menu bar (Reload config) or run this in the Hammerspoon console:

hs.reload()

Open the console (menu bar icon > Console). If you see Loading Spoon: Shoji and Shoji loaded: true, the installation worked.

Next steps

Continue to Quick start to start tiling.