View on GitHub

Kwm

Tiling window manager with focus follows mouse for OSX

download .ZIPdownload .TGZ

Kwmc Reference

Kwmc is a program used to write to Kwm's socket.

A command with {foo} means that an argument of that type is required.
A command with {foo?} means that an argument is optional.

Table of Contents:

Create Window Rules

NOTE: Some applications launched from the shell have to be whitelisted at startup. These applications have been flagged by OSX with a 'modeBackgroundOnly' flag, and can be allowed through by using:

kwmc whitelist processname


The window rule system is used to apply various properties to a range of applications or windows.

Window rules are not applied lazily, and a window will try to match multiple rules. Because of this, the order in which the rules are specified when combined, could impact the end result.

The pattern matching performed by the window filters uses std::regex and std::regex_match. For regular expression syntax, refer to ECMAscript specification or POSIX for detailed information.

A rule follows the general form:

kwmc rule owner="" name="" role="" properties={float=""; display=""; space=""; role=""} except=""

Window Filter

The window rule system allows you to filter windows based on the owner, title, accessibility role, and the potential custom role of a window.

The filter is specified using the below tags:

Filter Description
owner="" Matches the bundlename of an application.
name="" Matches the title of a window.
except="" Matches the title of a window that should be ignored.
role="" Matches the AXWindowRole and AXWindowSubrole of a window.
crole="" Matches the custom role that can be supplied through rules.

Window Properties

The following are the properties which may be applied to any window, through a rule.
The properties must be listed in a properties block, using ';' as a separator:
properties={property=""; property=""; ..}

The properties are specified using the below tags:

Property Description
float="true|false" Makes the window floating.
display="id" Moves the window to the given display, if it exists.
space="id" Moves the window to the given space, if it exists.
role="AXRole" Treat the window as if it was of type 'AXRole'.
scratchpad="visible|hidden" Matches the custom role that can be supplied through rules.

Example Rules

The following two rules allow Kwm to recognize all Finder windows of type AXDialog. If a finder window has an accessibility role or subrole equal to the type AXDialog, they will be marked as floating.

kwmc rule owner="Finder" properties={role="AXDialog"}
kwmc rule owner="Finder" role="AXDialog" properties={float="true"}

The following rule allows Kwm to tile borderless iTerm2 windows.

kwmc rule owner="iTerm2" properties={role="AXDialog"}

The following rule floats iTerm2 windows where title contains 'border', but not 'less'.

kwmc rule owner="iTerm2" name="border" properties={float="true"} except="less"

Configure Kwm

Reload config ($HOME/.kwm/kwmrc)

kwmc config reload

Override the optimal split-mode (golden ratio -> 1.618)

kwmc config optimal-ratio {ratio}
    {ratio}: floating point number

The container position to be occupied by new windows

kwmc config spawn {side}
    {side}: left | right

Automatically float non-resizable windows

kwmc config float-non-resizable {enabled}
    {enabled}: on | off

Automatically reapply container if window changes size

kwmc config lock-to-container {enabled}
    {enabled}: on | off

Set status of focus-follows-mouse

kwmc config focus-follows-mouse {enabled}
    {enabled}: toggle | on | off

Disable focus-follows-mouse when a floating window gains focus

kwmc config standby-on-float {enabled}
    {enabled}: on | off

Center window when made floating

kwmc config center-on-float {enabled}
    {enabled}: on | off

Allow focus commands to wrap

kwmc config cycle-focus {enabled}
    {enabled}: on | off

Set state of mouse-follows-focus

kwmc config mouse-follows-focus {enabled}
    {enabled}: on | off

Allow windows to be moved by dragging with mod+left_mouse and resized with mod+right_mouse

kwmc config mouse-drag {enabled}
    {enabled}: on | off

Specify modifier keys to be used for initiating mouse-drag

kwmc config mouse-drag mod {modifiers}
    {modifiers}: mod+mod+mod

Set split-ratio for containers

kwmc config split-ratio {ratio}
    {ratio}: 0 < floating point number < 1

Window Borders

Enable window border

kwmc config border {type} {enabled}
    {type}: focused | marked
    {enabled}: on | off

Set window border thickness

kwmc config border {type} size {thickness}
    {type}: focused | marked
    {thickness}: number

Set window border color

kwmc config border {type} color {color}
    {type}: focused | marked
    {color}: 0xaarrggbb

Set window border radius

kwmc config border {type} radius {radius}
    {type}: focused | marked
    {radius}: number

Global defaults

Set default tiling mode for Kwm

kwmc config tiling {mode}
    {mode}: bsp | monocle | float

Set default padding

kwmc config padding {padding}
    {padding}: top bottom left right

Set default container gaps

kwmc config gap {gap}
    {gap}: vertical horizontal

Display Defaults

Override default tiling mode for display

kwmc config display display_id mode {mode}
    {mode}: bsp | monocle | float

Override default padding for display

kwmc config display display_id padding {padding}
    {padding}: top bottom left right

Override default gap for display

kwmc config display display_id gap {gap}
    {gap}: vertical horizontal

Override dimension applied by 'center-on-float' for display

kwmc config display display_id float-dim {dimension}
    {dimension}: width height

Space Defaults

Set default bsp-layout for space

kwmc config space display_id space_id tree {layout_name}

Set default name for space

kwmc config space display_id space_id name {name}

Override default tiling mode for space

kwmc config space display_id space_id mode {mode}
    {mode}: bsp | monocle | float

Override default padding for space

kwmc config space display_id space_id padding {padding}
    {padding}: top bottom left right

Override default gaps for space

kwmc config space display_id space_id gap {gap}
    {gap}: vertical horizontal

Interact with Kwm

Quit Kwm

kwmc quit

Windows

Change focus between windows

kwmc window -f {selector}
    {selector}: north | east | south | west | prev | next | curr | window_id

Change focus between monocle-subtree windows

kwmc window -fm {selector}
    {selector}: prev | next

Swap window position

kwmc window -s {selector}
    {selector}: north | east | south | west | prev | next | mark

Adjust container zoom

kwmc window -z {mode}
    {mode}: fullscreen | parent

Toggle window floating

kwmc window -t {selector}
    {selector}: focused

Float next window to be created

kwmc window -t {selector}
    {selector}: next

Resize window to container size

kwmc window -r {selector}
    {selector}: focused

Modify container split-mode of window

kwmc window -c split-mode {mode}
    {mode}: toggle

Modify container type of window

kwmc window -c type {type}
    {type}: monocle | bsp | toggle

Modify container split-ratio of window in direction

kwmc window -c reduce {amount} {direction}
kwmc window -c expand {amount} {direction}
    {amount}: 0 < floating point number < 1
    {direction}: north | east | south | west

Move window on the current space

kwmc window -m {direction}
    {direction}: north | east | south | west | mark | xoff yoff

Move window to a different space

kwmc window -m space {space}
    {space}: workspace_id | previous | left | right

Move window to an external display

kwmc window -m display {display}
    {display}: display_id | prev | next

Mark the focused window

kwmc window -mk focused

Mark window in direction of focused window

kwmc window -mk {direction} {wrap}
    {direction}: north | east | south | west
    {wrap}: wrap | nowrap

Displays

Change focus between displays

kwmc display -f {display}
    {display}: prev | next | display_id

Set active split-mode of display

kwmc display -c {mode}
    {mode}: optimal | vertical | horizontal

Spaces

Set name of active space

kwmc space -n name

Change focus between spaces, skipping transitions animation
(mission control does not update, requires `killall Dock`)

kwmc space -fExperimental {space}
    {space}: workspace_id | name | previous | left | right

Set tiling mode of active space

kwmc space -t {mode}
    {mode}: bsp | monocle | float

Resize all windows to their container size

kwmc space -r {opt}
    {opt}: focused

Adjust padding of active space

kwmc space -p {mode} {side}
    {mode}: increase | decrease
    {side}: all | left | right | top | bottom

Adjust gaps of active space

kwmc space -g {mode} {direction}
    {mode}: increase | decrease
    {direction}: all | vertical | horizontal

Tree

Manage pseudo containers

kwmc tree -pseudo {action}
    {action}: create | destroy

Rotate window-tree of current space

kwmc tree rotate {degrees}
    {degrees}: 90 | 180 | 270

Save bsp-layout of window-tree of current space

kwmc tree save {file}
    {file}: filename

Restore bsp-layout of window-tree of current space

kwmc tree restore {file}
    {file}: filename

Scratchpad

Add the focused window to the first available scratchpad slot

kwmc scratchpad add

Remove the focused window from the scratchpad

kwmc scratchpad remove

Toggle visibility of the window associated with the provided slot

kwmc scratchpad toggle {visibility}
    {visibility}: number

Query current state

Get the state of borders

kwmc query border {type}
    {type}: focused | marked

Get active cycle-focus mode

kwmc query cycle-focus

Get state of float-non-resizable

kwmc query float-non-resizable

Get state of lock-to-container

kwmc query lock-to-container

Get state of standby-on-float

kwmc query standby-on-float

Get state of focus-follows-mouse

kwmc query focus-follows-mouse

Get state of mouse-follows-focus

kwmc query mouse-follows-focus

Windows

Get property of focused window

kwmc query window focused {property}
    {property}: id | name | split | float

Get id of window in direction of focused window

kwmc query window focused {direction}
    {direction}: north | east | south | west

Get property of marked window

kwmc query window marked {property}
    {property}: id | name | split | float

Check if two windows have the same parent

kwmc query window parent window_id1 window_id2

Get child position of window (left or right)

kwmc query window child window_id

Get list of visible windows on active space

kwmc query window list

Tiling

Get tilling mode to be used for new spaces

kwmc query tiling mode

Get child position used by new windows

kwmc query tiling spawn

Get the mode used for binary splits

kwmc query tiling split-mode

Get the ratio used for binary splits

kwmc query tiling split-ratio

Spaces

Get tag of the active space

kwmc query space active tag

Get name of the active space

kwmc query space active name

Get id of the active space

kwmc query space active id

Get name of the previously active space

kwmc query space previous name

Get id of the previously active space

kwmc query space previous id

Get list of all spaces on focused display

kwmc query space list

Scratchpad

List all occupied scratchpad slots and their associated window

kwmc query scratchpad list