Writing your own window manager: a KWin scripting experience
I spend most of my day between a terminal, an editor and a browser. Arranging windows with a mouse is hundreds of tiny movements a day, and every one of them costs attention.
Tiling window managers solve that: windows lay themselves out and you drive them from the keyboard. But they usually ask you to replace your entire desktop, and I did not want to give up KDE.
An existing plugin was available. I installed it, used it for a week, and then started writing my own.
This article is about that decision and what came out of it.
Why the existing solution was not enough
Let me be fair up front: the plugin was not bad. It worked.
The problem was elsewhere. My workflow had a handful of specific requirements, and each of them was either missing from the plugin or behaved differently. Every time, I was adapting myself to the plugin's idea of things.
That is small friction, but it repeats dozens of times a day. And that is exactly what tools get customised for.
The decision criterion, I think, is this: if you use a tool every day and it resists you every day, changing it is worth it. If you use it once a month, put up with it.
I was in the first case.
What a KWin script is
Technically it is a simple thing: KDE's window manager loads JavaScript scripts and gives them an API for manipulating windows.
The simplest possible script looks like this:
workspace.windowAdded.connect((window) => {
if (window.normalWindow) {
window.frameGeometry = { x: 0, y: 0, width: 1280, height: 1440 }
}
})You subscribe to an event and resize the window when it appears. All tiling logic is an elaboration of that same idea.
The set of things you need is small: a list of windows, their geometry, the screen size, and events (window added, closed, activated).
The first working version
I started with the simplest layout: one "master" window on the left, the rest stacked on the right.
The logic fits into a few functions:
- Build the list of managed windows (excluding dialogs and panels).
- Split the screen into master and stack areas.
- Put the first window in master and distribute the rest evenly in the stack.
- Recompute on any change.
A working version existed after one evening. And that is where I understood the main thing: the value of this project is not in the amount of code, it is in the fit.
Where the complexity comes from
The core logic is simple. Complexity appears at the edges, and it grows faster than you expect.
Here is what I ran into:
Which windows should be managed at all? Dialogs, popup menus, the panel — none of those should be tiled. You need a filter, and the filter is never complete.
Fullscreen and minimised windows. If the user maximises a window, the script must stay out of the way.
Multiple monitors. Each needs its own layout, and state must update when a window moves between them.
Activities and virtual desktops. When a window moves to another desktop it has to drop out of the current layout.
This list keeps getting longer over time. So I adopted one rule early: every new capability must be switchable off. If it misbehaves, you turn it off rather than abandoning the whole script.
What got added
Over a few months the script grew. It now has five layouts: vertical and horizontal master-stack, monocle (one window filling the screen), grid and spiral.
The most useful additions:
A scratchpad terminal. A terminal that appears and hides on one key. It turned out far more useful than I expected — I use it dozens of times a day.
A cheatsheet overlay. One key press shows the list of all shortcuts. The reason is simple: I kept forgetting the shortcuts I had invented myself. Later I made that list generate itself from the code, because the hand-written one went stale immediately.
A settings window. At first every setting lived in a config file. Then I built a simple form inside system settings. In a "just for me" project that may look excessive, but it freed me from editing files.
State persistence. This turned out to be the hardest part, and it is still incomplete: layout state is lost when KWin restarts. I left that as an accepted limitation, because solving it properly would take disproportionate effort.
Tests — an unexpected necessity
Writing tests for a personal project can seem excessive. For me it went the other way.
The reason is that window placement logic can be written as a pure function: in goes a list of windows and a screen size, out comes a list of geometries. Code shaped like that is extremely easy to test.
And they were badly needed, because every new layout threatened to break the old ones. The script now has 22 tests, and they give me confidence after every change.
There is an interesting contradiction here: I deliberately wrote no tests for my blog's comment system, because it is simple and the cost of a mistake is low. Here the logic is intricate and the regression risk is high. Same person — completely different decision, because the criterion is not the type of project but cost of failure and complexity.
The traps I fell into
A few are worth mentioning.
Reading configuration. The method described in the documentation did not work for me — a global function was required instead. Things like that are visible only in the source, not in the docs.
Autostart files. They require an absolute path. A relative path or the home-directory shorthand does not expand, and the service silently fails to start.
Keyboard shortcuts get cached. Change a shortcut in code and the old one lingers in the system cache. You have to clear it manually in system settings. Not knowing that cost me an hour.
Conflicts with other tiling plugins. With two active at once, they push each other's windows around. I added an automatic disable step to my install script.
Was it worth it
The honest answer: if you count time purely as savings, no.
Configuring the existing plugin would have taken a few hours. I spent several days.
But there are two other returns.
The first is that the environment now fits my workflow exactly. The friction that repeated daily is gone. A small thing, but it acts every single day.
The second, and the unexpected one, is that I understand my environment. Windows used to "just arrange themselves somehow". Now I know why they do what they do and can change anything I want. That feeling changed my whole experience of using Linux.
If you are considering a project like this, one piece of advice: start with the simplest working version. One layout, two shortcuts, no settings. Use it for a week. If you did not go back to it during that week, you did not need the project, and you spent one evening.
If you did go back — continue from there. That is exactly how it went for me.