Window filtering

Control which applications and windows participate in tiling. This page explains filtering behavior and examples. For the complete list of configuration options, see Configuration overview.

Filter modes

Shoji supports two filtering strategies:

Mode	Behavior
`blocklist` (default)	Tile all apps except those in `filter_apps`
`allowlist`	Tile only apps in `filter_apps`

Blocklist mode

Exclude specific apps from tiling. Good for apps with non-standard windows (Finder, System Settings) or apps that should remain floating:

spoon.Shoji:configure({
  filter_mode = "blocklist",
  filter_apps = {
    "com.apple.finder",
    "com.apple.systempreferences",
    "com.apple.Preview",
    "com.1password.1password",
  },
})

Excluded apps behave as floating windows that do not affect the tiled layout.

Allowlist mode

Tile only specific apps. Useful when working with a fixed set of apps and everything else should float:

spoon.Shoji:configure({
  filter_mode = "allowlist",
  filter_apps = {
    "com.apple.Terminal",
    "org.mozilla.firefox",
    "com.microsoft.VSCode",
  },
})

An empty allowlist would tile nothing, so Shoji treats it as a configuration error.

Finding bundle IDs

Every macOS app has a unique bundle ID. The most reliable way is Terminal:

osascript -e 'id of app "Safari"'

Replace “Safari” with the app’s name.

Common bundle IDs

Application	Bundle ID
Finder	`com.apple.finder`
System Settings	`com.apple.systempreferences`
Preview	`com.apple.Preview`
Terminal	`com.apple.Terminal`
Safari	`com.apple.Safari`
Firefox	`org.mozilla.firefox`
VS Code	`com.microsoft.VSCode`
iTerm2	`com.googlecode.iterm2`
Slack	`com.tinyspeck.slackmacgap`
1Password	`com.1password.1password`

Minimum window size

Exclude small windows from tiling. Useful for filtering dialogs, popups, and utility windows:

spoon.Shoji:configure({
  min_width = 400,   -- Minimum width in pixels
  min_height = 300,  -- Minimum height in pixels
})

Windows smaller than these dimensions remain floating. Set to 0 to disable size filtering.

Per-window floating

Toggle individual windows to floating regardless of filter settings. Bind the action:

spoon.Shoji:bindHotkeys({
  toggle_float = { { "ctrl", "alt", "shift" }, "t" },
})

Floating windows:

Do not participate in tiling calculations.
Can be freely positioned and resized.
Keep their floating state across retiles.
Reset to tiled when closed and reopened.

Combining filters

Filters work together. A window must pass all of them to be tiled:

App must not be in blocklist (or must be in allowlist).
Window must meet minimum size requirements.
Window must not be manually set to floating.

spoon.Shoji:configure({
  filter_mode = "blocklist",
  filter_apps = { "com.apple.finder" },
  min_width = 400,
  min_height = 300,
})

With this configuration, Finder windows always float, and windows from other apps smaller than 400x300 also float.