Installation

Shoji is built as a Hammerspoon Spoon. Hammerspoon is a macOS automation framework that gives Lua scripts access to window management, keyboard shortcuts, and other system APIs. You don’t need to know Hammerspoon to use Shoji, but it must be installed.

Compatibility

Shoji relies on the hs.spaces module for space-aware tiling. This module uses private macOS frameworks that require macOS 12 (Monterey) or later. Earlier macOS versions do not expose the APIs Shoji needs to query and manage Spaces.

Component	Tested with	Notes
macOS	12 (Monterey) and later	hs.spaces requires macOS 12+
Hammerspoon	1.0.0+	Requires hs.spaces support
Lua	5.4 (bundled)	Shipped with Hammerspoon; not user-configured

Known limitations:

• Accessibility permissions are mandatory. Hammerspoon needs Accessibility access to move and resize windows. Without it, Shoji loads but cannot tile.
• System Integrity Protection (SIP) must remain enabled. Hammerspoon’s hs.spaces relies on private frameworks that behave differently (or break) when SIP is disabled.
• Spaces API is read-only. Shoji can observe which Space a window belongs to but cannot move windows between Spaces programmatically. macOS does not expose a public or stable private API for this.
• Mission Control transitions. During Space switches and Mission Control animations, hs.spaces calls may transiently fail. Shoji handles this gracefully with fallback logic and retries.

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 (System Settings > Privacy & Security > Accessibility)
3. Confirm Hammerspoon appears in the menu bar

Accessibility permissions are required

Without Accessibility permissions, Shoji cannot move or resize windows. If tiling doesn’t work, check System Settings > Privacy & Security > Accessibility and ensure Hammerspoon is enabled.

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.

New to Lua?

Shoji’s configuration uses Lua. If you’re coming from another language, Learn Lua in Y Minutes covers the basics in a few minutes. You only need tables, functions, and strings to configure Shoji.

Having trouble?

See Troubleshooting for solutions to common setup issues.

Next steps

Continue to Quick start to start tiling.