Skip to content
Organize your unix desktops into a tree
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


Type Name Latest commit message Commit time
Failed to load latest commit information.

metadesk – Organize your Desktops into a Tree

Metadesk tree

Metadesk is a bspwm wrapper that organizes your desktops into a tree. This is useful for grouping related desktops together to, for instance, separate different tasks. Some features:

  • Construct and navigate an arbitrary tree of desktops
  • Automatically append and remove empty subdesktops
  • Add arbitrary string attributes to desktops, such as names or working directories
  • Subscribe to state changes, ready to pipe to status bars like lemonbar


You'll first need to set up go and bspwm. Then run:

$ go get


Similar to bspwm, metadesk uses a client-server model to control its state. A metadesk daemon, started with the metadesk command, is controlled using the mdc command. To control metadesk using hotkeys, you use a hotkey daemon like sxhkd to call mdc.

General mdc syntax


mdc applies the given command to the given selected desktop.

Selecting a desktop

A DESKTOP_SEL consists of an initial desktop selection and any number of subselectors:

<initial_sel> [SUBSELECTOR]*

<inital_sel> can be any of:

  • root the root desktop
  • focused the currently focused leaf desktop
  • last the most recently focused leaf desktop

A subselector can be any of:

  • -p | --parent select the parent of the currently selected desktop
  • -c | --child <n> select the child desktop at index n


Once a desktop is selected, a command is provided to act on the desktop.

Command Description
`-f --focus`
`-n --next`
`-p --prev`
`-a --add`
`-r --remove`
`-A --attrib `
`-A --attrib <name `
`-u --unset `
`-w --move-window`
`-s --swap `
`-F --focused-child`
`-C --child-count`
`-P --print `
`-S --subscribe `


Formatters are small functions which format the state of a desktop as a string. The --print and --subscribe command take a formatter name as an argument. By default, metadesk includes a tree formatter which recursively prints the state of all desktops, and a lemonbar formatter which formats the children of the root desktop for lemonbar. To create your own formatter, you can fork this repository and implement the server.Formatter interface.


Attributes are user-defined string key-value pairs stored in desktops. They can be accessed by mdc and formatters. For example, the default lemonbar formatter prints the name attribute of the root desktop's children.

You could use attributes to:

  • Store the current working directory of the desktop and open all new terminal windows in this directory
  • Store a color string for a formatter to use to output to a panel
  • Store some personal notes


A sample metadesk configuration which uses sxhkd and lemonbar is available in the examples directory.

Example mdc usage

Focus the second child of the root desktop:

mdc root -c 1 -f

Select the desktop next to the focused desktop:

mdc focused -p -n

Set the "cwd" attribute of the third child of the root desktop:

mdc root -c 2 -A cwd "$HOME/code"

Remove the last focused desktop:

mdc last -r

Continuously pipe the root desktop's state to lemonbar:

mdc root -S lemonbar | lemonbar


Please do! Pull requests are welcome.

Here are some possible extensions to work on:

  • Selectors to select sibling desktops
  • Attribute-based desktop selectors
  • Multihead support
  • React to external desktop focusing
  • Additional example formatters
You can’t perform that action at this time.