Skip to content
Shoji

Common issues

Fixes and workarounds for common situations where tiling behaves unexpectedly.

Transient windows

Spotlight, 1Password, dialogs, and other temporary windows can disrupt tiling when they appear and disappear. Add them to your blocklist so they float over the tiled layout. See App exclusions for ready-made patterns covering launchers, password managers, and system apps.

Full-screen apps

Shoji automatically skips native macOS full-screen windows and full-screen spaces. No configuration needed. If an app enters full-screen mode (the green traffic light button or Ctrl-Cmd-F), Shoji ignores it and tiles the remaining windows normally. When the app exits full-screen, it rejoins the tiled layout.

Video conferencing

Zoom, Teams, and other meeting apps create camera windows, sharing overlays, and floating toolbars that interfere with tiling. Exclude them via the blocklist. See App exclusions for bundle IDs covering Zoom, Teams, Google Meet, Webex, and Slack huddles.

Focus and mouse behavior

Shoji is keyboard-driven only. There is no focus-on-demand, focus-follows-mouse, or click-to-focus behavior built in. All window navigation uses hotkeys:

  • Directional: focus_left, focus_right, focus_up, focus_down
  • Sequential: focus_next, focus_prev
  • History: focus_last

This is a deliberate design choice. Mouse-based focus policies interact poorly with tiling managers because retiling moves windows under the cursor, causing unintended focus changes. Keyboard navigation gives predictable, consistent results.

See Navigation for the full list of focus actions and keybinding examples.

Apps that resize themselves

Some apps enforce their own window dimensions, fighting the tiling manager. Common offenders include Electron apps (Spotify, Discord) and apps with fixed aspect ratios.

Symptoms

  • A window snaps back to its preferred size after tiling.
  • Gaps appear where a window refuses to fill its assigned frame.
  • The layout recalculates repeatedly as the app and Shoji disagree on size.

Workarounds

Minimum size filtering prevents small, stubborn windows from entering the layout:

spoon.Shoji:configure({
  min_width = 400,
  min_height = 300,
})

Blocklist the app if it consistently fights tiling:

spoon.Shoji:configure({
  filter_mode = "blocklist",
  filter_apps = {
    "com.spotify.client",
    "com.hnc.Discord",
  },
})

Per-window floating lets you toggle individual windows out of tiling on the fly without changing your config:

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

See Window filtering for details on combining these approaches.