View on GitHub

Kwm

Tiling window manager with focus follows mouse for OSX

download .ZIPdownload .TGZ

Project Deprecated

Main development was shifted to a new window manager early 2017. Kwm was a nice proof of concept, but had many faults in its architecture.

The experience gained while working on kwm has been huge, and so I found that starting a complete re-write from scratch was necessary to create a stable window manager of higher quality. Despite the time and effort this requires, it would be worth it in the end.

This repository and the currently available documentation will remain as is, but I highly suggest using the new chunkwm instead.

Description

NOTE: The master branch is considered stable and can be used instead of the latest version by people who wish to do so.

Kwm started as a simple project to get true focus-follows-mouse support on OSX through event tapping. It is now a tiling window manager that represents windows as the leaves of a binary tree. Kwm supports binary space partitioned, monocle and floating spaces.

Kwm uses the event taps API (Quartz Event Services) to observe, filter and alter user input events prior to their delivery to a foreground application.

Kwm runs a local daemon to read messages and trigger functions. Kwmc is used to write to Kwm's socket, and must be used when interacting with and configuring how Kwm works. For a list of various commands and settings, view the Kwmc configuration reference.

For in depth information, sample configurations, and useful scripts to implement new features by combining Kwmc commands, check out the wiki. Khd can be used to create keybindings to perform some Kwmc command.

Kwm requires access to the OSX accessibility API. Tested on El Capitan (10.11.1 - 10.11.6).

img
For more screenshots, click here.

The bar seen in the above screenshot can be found here.

Usage

When Kwm starts, it will automatically tile the windows of the current space using the tiling mode set in the config file. By default, it will use binary space partitioning. This will also happen once for any other space the user might switch to.

When Kwm detects a new window, it is inserted into a window tree using an insertion point, with the given split-mode. When a window is closed, it will be removed from the window tree and the tree will be rebalanced. By default, the insertion point is the focused container, but a temporary insertion point can be set.

There are 3 types of split-modes available:

A node in the bsp-tree can be in 2 different states:

Example of a bsp-tree consisting of only Tree Nodes:

          a                       a                       a
         / \         -->         / \         -->         / \
        1   2                   1   b                   1   b
                                   / \                     / \
                                  3   2                   c   2
                                                         / \
                                                        4   3

---------------------   ---------------------   ---------------------
|         |         |   |         |         |   |         |    |    |
|         |         |   |         |    3    |   |         | 4  |  3 |
|         |         |   |         |    *    |   |         | *  |    |
|    1    |    2    |   |    1    |---------|   |    1    |---------|
|         |    *    |   |         |         |   |         |         |
|         |         |   |         |    2    |   |         |    2    |
|         |         |   |         |         |   |         |         |
---------------------   ---------------------   ---------------------

Example of a bsp-tree consisting of a monocle-subtree (a Link Node):

          a                       a                       a
         / \         -->         / \         -->         / \
        1   b                   1   b                   1   b
           / \                 /   / \                 /   / \
          3   2               4   3   2               4   3   2
                                                     /
                                                    5

---------------------   ---------------------   ---------------------
| SubTree |         |   | SubTree |         |   | SubTree |         |
|    1    |    3    |   |    1    |    3    |   |    1    |    3    |
|         |         |   |    |    |         |   |    |    |         |
|         |---------|   |    4    |---------|   |    4    |---------|
|         |         |   |         |         |   |    |    |         |
|         |    2    |   |         |    2    |   |    5    |    2    |
|         |         |   |         |         |   |         |         |
---------------------   ---------------------   ---------------------

If a window is not detected by Kwm, it is most likely due to a 'window role' mismatch. Use the window rule system to fix this. See #issue 40 for information.

Install

NOTE: Kwm requires 'Displays have separate spaces' to be enabled.

A codesigned binary release is available through Homebrew

  brew install koekeishiya/formulae/kwm

Manage Kwm using brew services

  brew services start kwm

Development

NOTE: Kwm requires 'Displays have separate spaces' to be enabled.

NOTE: Requires Xcode-8 command line tools.

Build AXLib only

  make install-lib  # release version, runs cleanlib
  make lib          # debug version

Build Kwm (also builds AXLib if required)

  make install      # release version, runs cleankwm
  make              # debug version

Remove temporary build artifacts

  make clean        # runs cleanlib and cleankwm
  make cleanlib     # remove axlib artifacts
  make cleankwm     # remove kwm artifacts

Start Kwm on login through launchd

  edit /path/to/kwm on line 9 of examples/com.koekeishiya.kwm.plist
  cp examples/com.koekeishiya.kwm.plist ~/Library/LaunchAgents/

Manually manage Kwm using launchctl

  launchctl load -w ~/Library/LaunchAgents/com.koekeishiya.kwm.plist

I would recommend for Kwm to be managed by launchd, as it otherwise requires the terminal application to have Accessibility Permissions (Not Recommended).

Configuration

The default configuration file is $HOME/.kwm/kwmrc and is a script that contains Kwmc commands to be executed when Kwm starts. This file can be used to blacklist applications and specify a variety of settings, as well as run any command not restricted to Kwmc.

View the Kwmc configuration reference

Kwm can apply all of these settings during runtime, and so live testing of options is possible before writing them into the config file.

A different path can be used by running kwm -c /path/to/kwmrc or kwm --config /path/to/kwmrc, in which case it would probably be a good idea to set the directories Kwm uses for various settings.

A sample config file can be found within the examples directory.

Donate

First of all, Kwm will always be free and open source, however some users have expressed interest in some way to show their support.

If you wish to do so, I have set up a patreon here.