The Problem

The window managers of normal people have finally driven me crazy. The two simple things I require seem to not be possible with less effort than writing my own window manager from scratch.

  • Let me clearly know when a window is in focus so I don’t type passwords into the wrong place.

  • On my 4k monitor I can not find the stupid mouse pointer. Changing the mouse behavior to something I’m happy with seems harder than creating a new window manager from scratch. Since requiring the mouse at all represents a failure of the system, I am interested in alternative approaches.

Normal window managers ostensibly support "themes" but in practice, it’s a complete mess. There are so many overlapping semi-compatible systems and the documentation is always very scant amounting to little more than: go to this sketchy web site, download a theme, use the automagical install (which doesn’t even work). I don’t want a theme — I want to make my focused title bars a bright color (if I must waste screen real estate with title bars). I have never found any sensible official documentation for that level of customization. I’m mystified by how people are creating these themes since there seems to be no documentation for how to do this comprehensively (i.e. not just editing someone else’s).

Why Awesome

I hate the name; it should be called "Tolerable WM". (Perhaps it’s balanced by one of its internal modules called "awful".) However, "Awesome", the window manager, seems to be customizable and focused on doing things in an optimal way. As with many of my other favorite programs, one thing that is completely unoptimized is how easy is it for pre-school children to use immediately with no training — this is the objective that normal systems have optimized at the expense of every other property. I’m a professional computer user so I’m willing to make a proper investment to get the optimal system for my needs.


Keyboard Shortcuts

The main modifier strategy for interacting with awesome is the key which I have almost never pressed since it first defaced keyboards in the 1990s. But today, I can concede the absurd ubiquity of this idiot keyboard addition and what better use could it possibly have than to drive your window management system? So I’m fine with using keycode 133 (keysym 0xffeb, Super_L). This is usually referred to in documentation as "Mod4". Normal people know it as "the windows key".

Awesome Specific Functions

  • [W] + s - Show keybinding help.

  • [W] + [C] + r - restart awesome.

  • [W] + [S] + q - quit awesome.

  • [W] + Enter - Spawn terminal.

  • [W] + r - Run prompt.

  • [W] + w - Open main menu at mouse cursor.

Client Size And Focus

  • [W] + m - Maximize client toggle.

  • [W] + n - Minimize client. Note that they disappear!

  • [W] + [C] + n - Un-minimize client. Looks like they reappear from a FILO queue.

  • [W] + f - Make client full screen, toggle.

  • [W] + [S] + c - Kill focused client.

  • [W] + t - Bring client to top.

  • [W] + j - Focus on next client.

  • [W] + k - Focus on previous client.

  • [W] + [S] + j - Switch client with next client.

  • [W] + [S] + k - Switch client with previous client.


Note that if you accidentally hit [W]+space, it can be very disorienting and it can seem like you’re stuck in tiling mode. The important insight is that it will eventually cycle back around to floating mode, but the windows on the screen won’t reorganize themselves back to the way you had them.

  • [W] + space - Reorganize using next layout.

  • [W] + [S] + space - Reorganize using previous layout. Helpful for recovering from an accidental [W] + space (then reposition your windows back to where you had them in floating).

  • [W] + [C] + space - Toggle client floating status for the active window.

Master And Urgent

  • [W] + h - Decrease master width factor by 5%.

  • [W] + l - Increase master width factor by 5%.

  • [W] + [S] + h - Add another window to master list.

  • [W] + [S] + l - Remove a window from master list.

  • [W] + [C] + Enter - Swap focused client with master.

  • [W] + u - Focus on first urgent client. I don’t quite understand what "urgent" means to this wm.


  • [W] + → - Switch to next tag.

  • [W] + ← - Switch to previous tag in the list.

  • [W] + 1-9 - Switch to tag number 1-9.

  • [W] + Esc - Switch to last used tag.

  • [W] + [C] + 1-9 - Toggle specified tag view.

  • [W] + [S] + 1-9 - Tag client with specified tag.

  • [W] + [S] + [C] + 1-9 - Toggle client tag with specified tag.


  • [W] + o - Send client to next screen.

Command Line

You can use the awesome-client to interact with your session.

$ awesome-client 'awesome.restart()'
$ awesome-client 'awesome.quit()'


This seems to want to be a huge mess — exactly like all other window manager swamps. However, there is an end to the configuration rabbit hole with awesome.

I believe the master default configuration lives here.


To override it you need to have your own here.


I don’t get the feeling that these cascade in any elaborate way. It just uses the first one it can find starting with the users'.

Many important things live in places like this.



Many people like to have familiar applications start cluttering the screen right away when the system starts. I do not. However, there are some things that must be run immediately to avoid screen "saving" annoyances.

I derived my strategic approach from the ArchWiki. Start by making one of these.

touch ~/.config/awesome/

Make it executable and fill it with this.

#!/usr/bin/env bash
function run1x {
    if ! pgrep -f $1 ; then
        $@ &

xset s off
xset s -dpms
run1x xcompmgr

The run1x function is to sensibly check if the thing you want to run is already running (and ignore it if so). I don’t do this check for the xset commands because if I turn that damn screen blanking off a million times it won’t be enough.

Then add this line in ~/.config/awesome/rc.lua right after all the "local" definitions are set.

- == Start Up Sourcing ==

With that in place, the window manager will come up ready to go.


Along with wibox shown above, this seems to be where the libraries are kept.

  • awful

  • bashets.lua - use shell scripts in Awesome widgets.

  • beautiful - library that allows you to theme awesome using an external file, it becomes theoretically possible to dynamically change your whole awesome colours and wallpaper without changing your rc.lua.

  • cyclefocus

  • flaw

  • freedesktop - compliant with, where XDG (cross desktop group) comes from.

  • gears - Handles wallpaper. Maybe other things.

  • menubar

  • naughty - Pop up notifications.

  • obvious -

  • revelation - Bring up a view of all opened clients.

  • tyrannical

  • vicious - Modular widget library for window managers to help with custom widgets.

  • wibox


The beautiful plug in allows theme frivolity to live in its own space. This, in theory, allows frantic theme adjustment without messing with your more serious configuration setup.

The default is /usr/share/awesome/themes/default. There are others provided.

  • default

  • gtk

  • sky

  • xresources

  • zenburn

To use the themes do something like this.

cp /usr/share/awesome/themes/default ~/.config/awesome/themes/

Edit this in rc.lua to match.

beautiful.init(awful.util.getdir("config") .. "/themes/default/theme.lua")


One of my primary motivations for using this window manager was to emphatically assert my dominance over windows that could not properly make it clear that they were focused. Although I’ve typed passwords into millions of correctly focused windows, the couple of mistakes that slipped past me were too much to bear. I found that configuring awesome to do what I needed was pretty easy.

In the theme.lua file just change these.

theme.bg_normal= "#CECECE22"
theme.bg_focus== "#FF4422"

Title Bar Placement

After using the previous title bar scheme where the focused client was very brightly colored, I found that most of the remaining focus mistakes I make are because I’m jumping back and forth between an open editor and a terminal where I’m running the code I’m editing. The problem is that it does not take long to be at the bottom of the screen when running commands. When writing a file in Vim, you’re looking at the bottom too. I realized that my eyes were seldom looking at the top of the screen and that really interesting and important signals should be brought to my attention at the bottom. So I wondered if it was possible to move the title bars with their critical focus color cues to the bottom of the windows. The answer is yes. Just add this attribute to your rc.lua setup line.

awful.titlebar(c,{position="bottom"}) : setup {

More technical details are here.


But wait there’s more! As an added bonus you can use transparency to really make the focused windows, well, focused. Unlike other systems a minimal system like awesomewm doesn’t have any native abilities to composite transparent scenes. Fortunately, there are many options. This is what mysterious things like compiz do. I also found compton and xcompmgr. I went with the latter with a simple apt install xcompmgr. Then dress up these lines of the rc.lua configuration file.

client.connect_signal("focus", function(c) c.border_color = beautiful.border_focus c.opacity=1.0 end)
client.connect_signal("unfocus", function(c) c.border_color = beautiful.border_normal c.opacity=0.4 end)

Nothing much will happen, but when you turn the compositor on, all the unfocused windows fade into the desktop background. To turn it on, just run it somehow, for example type xcompmgr into a terminal. All the unfocused stuff will fade into the background. Cool.

This wiki page has a nice example of putting the xcompmgr feature into a Bash script that you can deploy as needed, perhaps with an awesomewm keybinding.

Wibox And Wibar

Some people like omnipresent clutter on their screens. I do not. I do not like icons. I really do not like horizontal things that waste the valuable dimension to my monitor like title bars. This also means I prefer not to see any "helpful" panels that imagine you don’t know what you are doing and will be most comfortable painfully fumbling for guessed solutions with a mouse.

In Awesome I believe this annoying (but sort of important) menu bar thing is called the wibar.

Pavel claims to have a way to toggle the systray with a keyboard shortcut. That is acceptable.

Maybe it can just be made transparent. In theory something like this can make it 50% transparent (the 88 out of FF).

s.mywibox= awful.wibar({ position = "top", screen = s, bg = "#CECECE88" })

Hmm. Actually, changing theme.bg_normal to such a color in mytheme/theme.lua was a big help.

Note that this wibar stuff seems to be based on a more ancient wibox system (maybe an extension, maybe a replacement). Rumor has it that awful.wibar is a specialized wibox designed to be attached to an edge of the screen.

Note that there is a position attribute that can be left, right, top, or bottom. I also changed instances of wibox.layout.fixed.horizontal to wibox.layout.fixed.vertical. It isn’t perfect, but it’s closer to what I want.

A wibox seems to be a new client window managed by awesome. Here is official documentation about what all the pieces are called.

Stupid Bar Widgets

Fancy things can be done with Awesome. But to start with you usually just need to get some basics figured out to not be stuck. For example, there is no fancy wifi/network icon in the top bar.

So how do you configure your network? I have had decent luck just using nmtui. You can also type nm-applet (assuming some other window management system left it lying around) and do what you normally do with the bar. Slip that into the initialization process for awesome if you need that frequently.


Awesome has quite a few layouts that you can dynamically cycle through at runtime. The sad problem is that none of them do what I want. What I want seems pretty simple and obvious — I want the screen do always divide vertically. Easy, right? A close but not quite system can be found here. This does exactly what I want until the fourth window and then it starts splitting horizontally (which I never want). It should be useful for inspiration though.

Power Issues

I found that if I left my default Awesome setup for too long one of the thousands of screensaverish processes that compete for attention would turn off or hibernate or suspend the screen. With new activity it would come back on, but then a very strange effect presented itself — the screen did not reflect the new actions, however, if I did a Ctrl-Alt-F2 to get to a text console and then came back to the graphical session, the things I had done were now manifest. But new actions still didn’t have any apparent effects. So basically actions were being honored, but the visible effects of them only seemed to show up when the graphics display was somehow updated in a major way.

I think I cured that with this.

sudo systemctl stop upower

Obviously this will have consequences but I don’t like my screens blanking without my explicit command.

Probably there is more to be done. Perhaps this also will help.

xset s off
xset -dpms
xset s noblank


After making changes to the configuration files definitely check the syntax with awesome -k. That doesn’t catch all errors, but it catches the most embarrassingly stupid ones.

The Awesome FAQ has a good tip for finding where any error messages are logged.

$ ls -l /proc/$(pidof awesome)/fd/2

For me that was /home/xed/.xsession-errors.

Problems With Steam And Tabbing Out Of Games

When playing Steam games, you often need to tab out by switching desktops. Everything is going fine, except when you return to the game desktop to resume, the (previously full screen) game is missing and cycling through applications does not bring it up. I found a solution.

First you must learn the window manager’s ID for this application:

$ wmctrl -l
0x00626ef8  1 x Terminal
0x05400005  1 x Deus Ex: Human Revolution - Director's Cut
0x0060002c  0 x screen

It’s best to just use the numeric ID since the text can be messy. As far as I can tell the problem seems to be that the "hidden" setting of the window is not revoked upon returning.

$ wmctrl -v -i -r 0x05400005 -b toggle,hidden

After executing that command, you should be back in business.

Here’s a way to do it with one single line.

$ wmctrl -vir $(wmctrl -l | grep "Deus Ex" | cut -d' ' -f1) -b toggle,hidden

Problems With The Inkscape Docking Tools Disappearing

You’re trying to use Inkscape to do ordinary boring things. You want to align some objects or change the stroke and fill or do a transform… hmmm… Where did those menu boxes go? They should be there. [C][S]-f should open up Fill and Stroke somewhere. I tried all kinds of things before stumbling onto the answer of resizing the entire window with [W]-RMB, specifically play with that right side. Immediately upon doing this, it popped into place!