This is the help page for SimplyWM.

The configuration file can be found at ~/Library/Application\ Support/simplywm.yml.

Changes to the file are applied immediately. There are no defaults for if the file/section is empty.

Same Configuration File

This is a sample configuration file:

layouts:
- tall
- fullScreen
keyboardShortcuts:
  previousLayout: ''
  nextLayout: F8
  moveToPreviousScreen: ctrl+shift+leftArrow
  moveToNextScreen: ctrl+shift+rightArrow
  swapWindowWithMain: ctrl+shift+return
unmanagedWindows:
- id: com.apple.iphonesimulator
- id: com.google.Chrome
  title: MetaMask*
appShortcuts:
  - app: Alacritty
    shortcut: ctrl+shift+v

Sections

The sections are:

layouts
keyboardShortcuts
unmanagedWindows
appShortcuts

Layouts

List the layouts enabled with a list under layouts:

layouts:
- tall
- fullScreen
- widescreenTall

The choice of layouts are intentionally limited (at the moment?).

See rationale for adding widescreenTall

Layout-Specific Configuration

Some layouts have configuration specific to them.

For widescreenTall, fullHeightWindowsCount specifies how many full-height windows there are, before stacking them vertically in the last column:

layoutSpecific:
  widescreenTall:
    fullHeightWindowsCount: 3

Keyboard Shortcuts

Configure keyboard shortcuts with keyboardShortcuts:

keyboardShortcuts:
  previousLayout: ''
  nextLayout: F8
  moveToPreviousScreen: ctrl+shift+leftArrow
  moveToNextScreen: ctrl+shift+rightArrow
  swapWindowWithMain: ctrl+shift+return
  moveWindowUpList: ctrl+shift+cmd+upArrow
  moveWindowDownList: ctrl+shift+cmd+downArrow

These are the modifiers available:

shift
control / ctrl
option / opt
command / cmd

These are the keys available:

return / enter
delete
deleteforward
end
escape
help
home
space
tab
pageup
pagedown
uparrow / up
rightarrow / right
downarrow / down
leftarrow / left
f1
f2
f3
f4
f5
f6
f7
f8
f9
f10
f11
f12
f13
f14
f15
f16
f17
f18
f19
f20
keypad0
keypad1
keypad2
keypad3
keypad4
keypad5
keypad6
keypad7
keypad8
keypad9
keypadclear
keypaddecimal
keypaddivide
keypadenter
keypadequals
keypadminus
keypadmultiply
keypadplus
a-z

The right-hand side of the keyboard shortcuts are case-insensitive. i.e. f8 and F8 are the same. Ditto for pageup and PageUp.

Unmanaged Windows

List exceptions for windows that you want to keep as unmanaged by SimplyWM with unmanagedWindows. Each of them can be any of these:

bundle identifier
title
bundle identifier and title

unmanagedWindows:
- id: com.apple.iphonesimulator
- id: com.google.Chrome
  title: MetaMask*

App Shortcuts

Configure app shortcuts with appShortcuts:

appShortcuts:
  - app: Alacritty
    shortcut: ctrl+shift+v

Refer to the Keyboard Shortcuts section for the list of available shortcut keys and modifiers.

App shortcuts are keyboard shortcuts that let you launch or switch to an app. If the currently focused window is the app, it will hide all windows for that app instead.

e.g. with this configuration:

appShortcuts:
  - app: Alacritty
    shortcut: ctrl+shift+v
  - app: Messages
    shortcut: ctrl+shift+m

I press ctrl+shift+v to launch/hide Alacritty and ctrl+shift+m to launch/hide Messages.

Every item in the list consist of the app which must match the app name and the keyboard shortcut. You can also specific an absolute path for app like /Applications/Xcode.app/Contents/Developer/Applications/Simulator.app. This is particularly useful when you have multiple versions of the same app.

Some apps have a different app name (CFBundleName) than the name of the app.

Eg. to launch Chrome, this is good enough:

  - app: Google Chrome
    shortcut: ctrl+shift+s

But press ctrl+shift+s doesn’t hide Chrome because app’s name specified by CFBundleName is actually “Chrome” and not “Google Chrome”. So in this case, you want to specify the bundle identifier too, and this will make ctrl+shift-+ launch and hide Chrome correctly:

  - app: Google Chrome
    shortcut: ctrl+shift+s
    id: com.google.Chrome