eigenclass logo
MAIN  Index  Search  Changes  PageRank  Login

ruby-wmii: Ruby configuration/scripting for the wmii window manager

ruby-wmii a fairly powerful Ruby script to configure and script the wmii-3 WM. It is much larger and more complex than the sample shell script included in wmii-3, but in exchange it allows you to code fairly complex behavior easily (for instance, ruby-wmii includes a powerful keyboard-controlled bookmark manager), and the basics work better in several ways:

  • tracking and disposal of child processes
  • protection against runtime errors, so wmiirc doesn't die leaving you with a broken environment
  • auto-updating program lists with caching
  • powerful internal actions without external scripts
  • logging

wmii compatibility

ruby-wmii works with wmii-3.1. The internal FS layout is routinely broken on each wmii release, and I've been waiting for an official release of wmii-3.6 for a while but it never seems to arrive, so I'm staying with my current setup, which works just fine.

If you want to use ruby-wmii, you'll need:

  • wmii-3.1.tar.gz
  • this two-line patch, if you want to use the ruby-ixp branch, which feels snappier than the trunk (that's the branch I'm using currently, so there are probably more bugs in the trunk). Note that ruby-ixp leaks memory, but this is not a problem since you can restart wmiirc without leaving X once a day or so with Alt+a wmiirc (you could easily have it restart automatically too).

Installation and usage

The latest version is ruby-wmii-0.3.1.tar.gz. You can read the release notes and report bugs here.

Older release notes:

darcs repository

You can find the repository (including head and other development branches) at http://eigenclass.org/repos/ruby-wmii


Run the included install.rb script with

 ruby install.rb

to install wmiirc and the standard plugin.

You'll be shown a help message with xmessage the first time you restart wmii if it's the first time you run ruby-wmii or you're upgrading from an older version. You can also find it at the top of the wmiirc script, or get it with

 Alt-a config-help


You can edit $HOME/.wmii-3/wmiirc-config.rb and reload the configuration with Mod1-a -> wmiirc as often as needed until you're satisfied with the result.

I'm very interested in innovative key bindings --- the usability space is best explored in parallel. Feel free to contact me at <mfp@acm.org> (any feedback appreciated; please add 'wmii' to the subject line to get past the spam filters).

Third party plugins, configurations, tips & tricks...

This is a wiki after all! Feel free to share your tips, point to your plugins... on the "community" page.

Advanced functionality

ruby-wmii includes

  • modal key bindings: raw (pass-through) and normal
  • volume control with the mouse wheel
  • namespaces (subtagging)
  • internal actions: browser, google, rename-view, screenshot
  • working set inference
  • many tagging/retagging mechanisms
  • most convenient bookmark management (complete-as-you-type, powerful searching, del.icio.us syncing...)

Several applets:

  • mpd: control the Music Player Daemon
  • battery-monitor
  • configurable status bar
  • volume control
  • most convenient bookmark management (complete-as-you-type, powerful searching, del.icio.us syncing...)



You can read the FAQ (and add your questions) here.

Default behavior

Key bindings

These are the default aliases:

   MODKEY   Mod1
   MODKEY2  Mod4  (often win key)
   UP       k
   DOWN     j
   LEFT     h
   RIGHT    l
MODKEY2-space        Switch between raw and normal input modes.
                     The current mode is indicated in the bar. All other key
                     bindings are ignored in raw mode.
MODKEY-Control-y     Run program with given tag (uses wmiimenu twice to get
                     the tag and the program).
MODKEY-a             Ask for action and execute it.
                     Includes internal and external (i.e. dependent on a
                     script in $HOME/.wmii-3) actions. Remembers the last
                     actions executed and presents them at the beginning.
MODKEY-p             Ask for a program and execute it.
                     The list of programs is updated periodically and cached.
                     Remembers the last programs executed and presents them at
                     the beginning.
MODKEY-0..9          Choose either the corresponding numerical view (if it
                     exists) or the (N-last_numerical_view)th non-numeric view
                     e.g. if the views are  1 2 3 4 code irc web
                     and you press MODKEY-6, it'll take you to  irc
MODKEY-Shift-0..9    Either replace the the numeric tag of the current client
                     or retag it as the (N-last_numerical_view)th non-numeric
MODKEY-t             Ask for view to move to.
                     Tries to sort the choices intelligently based on
                     previous movement.
MODKEY-LEFT          Select prev column.
MODKEY-RIGHT         Select next column.
MODKEY-UP            Select prev client.
MODKEY-DOWN          Select next client.
MODKEY-space         Toggle managed/floating layer.
MODKEY-d             Set default mode.
MODKEY-s             Set stacked mode.
MODKEY-m             Set max mode.
MODKEY-f             Maximize current floating client.
MODKEY-i             Move bottom of current client down (i.e. enlarge)
MODKEY-Shift-i       Move bottom of current client up (i.e. shrinken).
MODKEY-Return        Launch terminal.
MODKEY-Shift-LEFT    Send to prev column.
MODKEY-Shift-RIGHT   Send to next column.
MODKEY-Shift-DOWN    Swap with lower client.
MODKEY-Shift-UP      Swap with upper client.
MODKEY-Shift-space   Toggle managed/floating layer for client.
MODKEY-Shift-c       Kill current client
MODKEY-r             Go back to previous view (where we came from).
                     Pressing more than once makes you cycle between 2 views.
MODKEY-comma         Move to (lexicographically) preceding view.
MODKEY-period        Move to (lexicographically) following view.
MODKEY2-comma        Move to (lexicographically) preceding view within
                     current namespace.
MODKEY2-period       Move to (lexicographically) following view within
                     current namespace.
MODKEY-Shift-t       Retag current client. Allows +/- modifiers to add/remove
MODKEY-Shift-r       Retag current client and move to corresponding view.
                     Alloes +/- modifiers.
MODKEY2-Shift-t      Retag in the namespace. Given a client tagged as foo+bar:
                       baz   retags it as bar:baz
                       +baz  retags it as foo+bar+bar:baz
                     Given foo+bar:baz, -baz  retags as  foo
MODKEY2-Shift-r      Retag as MODKEY2-Shift-t and moves to new view.
MODKEY2-a..z         Jump to first view whose name starts with the given
                     letter, sorted with intellisort (favors views chosen
MODKEY-plus          Move forward in view history
MODKEY-minus         Move backwards in view history.
MODKEY-b             Open bookmark (see README.applets for further
MODKEY-Shift-b       Bookmark URL in X11 primary selection buffer. Again, see

Internal actions (MODKEY-a)

 browser:     if given an argument, open the given URL in a browser, otherwise
              ask for it
 google:      same as 'browser', but searches with google
 screenshot:  takes a screenshot in $HOME/tmp/NAME-IDX.png, where NAME is
              either the given parameter or 'screenshot', and IDX is
              incremented automatically
 rename-view: change the name of the current view, and retag all clients
              accordingly. Takes the new name as a parameter, or asks for it.
 wmiirc:      reload the wmiirc configuration
 config-help: shows information about how to use and configure wmiirc, as well
              as how to write plugins


ruby-wmii is licensed under the same terms as Ruby; see LICENSE.