Technology moves fast! ⚡ Don't get left behind.🚶 Subscribe to our mailing list to keep up with latest and greatest in open source projects! 🏆

Subscribe to our mailing list


Tiling window manager with focus follows mouse for OSX

Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star half bd79095782ee4930099175e5ce7f4c89fa3ddabcd56fffcc7c74f6f2a2d46b27 (1 ratings)
Rated 4.5 out of 5
Subscribe to updates I use kwm

Statistics on kwm

Number of watchers on Github 3438
Number of open issues 63
Average time to close an issue 8 days
Main language C++
Average time to merge a PR about 7 hours
Open pull requests 6+
Closed pull requests 11+
Last commit about 2 years ago
Repo Created almost 4 years ago
Repo Last Updated over 1 year ago
Size 2.56 MB
Organization / Authorkoekeishiya
Latest Releasev4.0.5
Page Updated
Do you use kwm? Leave a review!
View open issues (63)
View kwm activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating kwm for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)
What people are saying about kwm Leave a review
tiling like i3 wm


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 Build Status

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. Khd can be used to create keybindings to perform some Kwmc command. More info can be found in the example dir.

For in depth information, click here. For sample configurations and other useful scripts, check out the wiki. You can also drop by the channel ##kwm on freenode.

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.


A codesigned binary release is available through Homebrew

brew install koekeishiya/formulae/kwm

Manage Kwm using brew services

brew services start kwm

Copy the example config to ~/.kwm/kwmrc as described in the brew caveat section. If you'd like to use a different config file path: instead of using brew services, start Kwm using a custom launchd launch agent as described below in Starting *Kwm* on login through launchd.


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

Set directories used by Kwm for various settings.


-v | --version: Print version number to stdout
    kwm -v

-c | --config: Specify location of config file
    kwm -c ~/.kwmrc


NOTE: Documentation of available commands

The default configuration file is $HOME/.kwm/kwmrc and is a script that contains kwmc commands to be executed when Kwm starts.

A sample config file can be found within the examples directory. Any error that occur during parsing of the config file will be written to stderr.

Syntax highlighting for configuration files


Copy the vim syntax files to your vim config:

cp -r syntax/vim/* ~/.vim/

Or using pathogen:

cp -r syntax/vim ~/.vim/bundle/kwm


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 using launchd as described below.

Starting Kwm on login through launchd

Provide your own custom launch agent

  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


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.

kwm open issues Ask a question     (View All Issues)
  • over 2 years [feature request] - move focus to next monitor
  • over 2 years [master] Float next window to be created on space
  • over 2 years [MASTER] Spacemacs / Emacs not tiling and not following focus follows mouse
  • over 2 years [master] Weird borders
  • over 2 years [master] bug when monocle subtree becomes only window
  • over 2 years [master] Faulty AXEvent_DisplayChanged
  • over 2 years [master] Race conditions
  • over 2 years XMonad-style spaces
  • over 2 years [master] AXLibGetFocusedWindow crash
  • over 2 years [master] Extend center-on-float to work with windows floating because of a rule and float-non-resizable
  • over 2 years [master] Expand mouse-drag functionality to allow changing splits with a different modifier + left click
  • over 2 years [master] Mouse drag functionality flipped
  • almost 3 years What is the purpose of monocle subtrees?
  • almost 3 years Weird behavior with KakaoTalk
  • almost 3 years [3.1.3] Switch between subtrees
  • almost 3 years [3.1.3] Window resizing on move from primary display to the secondary one
  • almost 3 years mouse-drag does not initiate on an unfocused window
  • almost 3 years Documentation: Better explanation of what this is? (instead of how it works...)
  • almost 3 years [master] Safari preference window tiling behavior issue
  • almost 3 years Window tag (grouping)
  • almost 3 years Focus follows mouse: proposed behavior change
  • almost 3 years [3.1.3] Won't shift focus on iTerm2 windows without titlebar
  • almost 3 years [master] Move window between spaces (Mission Control)
  • almost 3 years [master] crash when display is awakens?
  • almost 3 years [master] Crash with display configured as mirror
  • almost 3 years [master] Move window between displays (Mission Control)
  • almost 3 years Focus follows mouse does not disable for google calendar notification popup
  • almost 3 years Border does not switch to iTerm window if "Hide iTerm2 from the dock" preference is enabled
  • almost 3 years [master] No border on application
  • about 3 years disable border on specific space
kwm open pull requests (View All Pulls)
  • kwm: listen for display resolution change & update
  • Don't move cursor if it's already over focused window
  • link directly against swift
  • Drag between displays
  • Focus by application name.
  • Added 'owner' queries for focused and marked windows
kwm list of languages used
kwm latest release notes
v4.0.5 Kwm 4.0.5

Version 4.0.5

The previous homebrew tap has been deprecated and is not updated beyond version 4.0.4. This warning has been out for roughly 6 weeks and was also mentioned in the caveat section during installation of the 4.0.4 version. See here if you somehow missed this.


  • focus-follows-mouse does not trigger when the alt-key is down.
  • Focus window by application name (e.g:kwmc window -f Emacs).
v4.0.4 Kwm 4.0.4

Version 4.0.4


  • Get rid of unnecessary heap allocation.
  • Fixed potentially huge memory leak, clearBorder should only clear the border and not release its handle. (#540)
  • Add support for right (rctrl) and left control (lctrl) modifier for mouse-drag key.
v4.0.3 Kwm 4.0.3

Version 4.0.3

NOTE: The previous certificate expired and I had to create a new one. Because of this, accessibility access must be re-approved for this version!


  • Fixed an issue where tiling could cause a native fullscreen window to freeze. (#524 #527)
  • Fixed an issue that would occur where a display_changed event was sent by OSX, despite
    no actual change in active display happening. (#516)
  • Fixed crash upon trying to restore nonexistant bsp-layout. (#543)
  • Center-on-float should now correctly apply to windows made floating through rules. (#510)
  • Cycle-focus is now properly applied to kwmc window -s next | prev. (#546)
  • Cycle-focus is now properly applied to monocle-subtrees. (#492)
  • Improved default bsp-split logic. (#553)
  • Add command to float the next created/detected window. (#525)
    kwmc window -t next
  • The init script ($HOME/.kwm/init) has been removed because of redundancy. (#557)
  • Code cleanup.
Other projects in C++