musca man page

musca — A simple dynamic window manager


musca [Options]


Musca is a simple dynamic window manager for X, with features nicked from ratpoison and dwm.

Musca operates as a tiling window manager by default. It uses "manual tiling", which means the user determines how the screen is divided into non-overlapping frames, with no restrictions on layout.

Application windows always fill their assigned frame, with the exception of transient windows and popup dialog boxes which float above their parent application at the appropriate size. Once visible, applications do not change frames unless so instructed.

Since not all applications suit tiling, a more traditional stacking window manager mode is also available, allowing windows to float at any screen location and overlap.

There are no built in status bars, panels, tabs or window decorations to take up screen real estate. If the user wants any of these things, there are plenty of external applications available to do the job. Window decoration is limited to a slender border, which is coloured to indicate keyboard focus.

Windows are placed in named "groups" which can be used in a similar fashion to virtual desktops. Groups can be added and removed on the fly, and each group has its own frame layout.

The excellent "dmenu" utility is being used to execute commands and launch applications, and it can also act as a window and group switcher. Basic EWMH support allows use of common panels, pagers and the wmctrl utility.

Windows and frames are navigated and focused on any mouse button click, including rolling the wheel, or alternatively driven entirely by the keyboard. Simple key combinations exist for window switching, group switching, frame control and screen switching.

For more information about Musca visit


These command line options are recognized by Musca:

-c [command]
Connect to a running instance of Musca and execute a single Musca command
supplied on the command line.
Connect to a running instance of Musca and execute one or more EOL delimited
Musca commands supplied on stdin.
-s [path]
Override the "startup" setting by specifying a custom path to a configuration
file holding Musca commands to execute at startup.
Report version number.


During initialization, Musca will read the ~/.musca_start configuration file or any other text file which was specified by the 'startup' setting in config.h during compilation.

The startup file should contain Musca commands one per line. Any comments must be on separate lines starting with hash (#). Blank lines are acceptable.

For example:

manage off trayer
manage off Conky

screen 1
name bling
pad 0 0 0 32
exec trayer
exec conky

screen 0
add mail
add net
add work
use mail
exec firefox
exec evolution
hsplit 1/2

set notify notify-send -t 3000 Musca "$(cat)"

Note that launching applications from the startup file is acceptable, but can be of limited use if they have to start in more than one group. The 'exec' command runs asynchronously, and if applications are slow to create their windows, they may not necessarily appear in the expected group. In this case, a better option is launching applications from ~/.xinitrc.

Musca Commands

add <name>
create a new group called `name`, and switch to it.
alias <name> <command>
create a new Musca command.
bind <on|off> <Modifier>+<Key> <command>
bind a Musca command to a key combination with `on`, and remove it
again with `off`. If the argument to `off` is `all`, it clears the
bound key list. The `command` argument is only need for `on`.
border <on|off|flip>
(toggle) turn the current frame border on and off.
catchall <on|off|flip>
(toggle) set the current frame as a `catch-all`, where all new windows
will open.
client hints <on|off>
(toggle) whether to respect X size hints for the current application window,
such as PMinSize, PMaxSize, PResizeInc, PBaseSize, PAspect.
launch the dmenu Musca command input.
cycle <local> <next|prev>
cycle a hidden window into the current frame. `local` means
cycle over windows previously displayed in the current frame.
`next` or `prev` specify the direction, defaulting to next.
Both arguments are optional.
dedicate <on|off|flip>
(toggle) dedicate the current frame to the current application.
drop <name|nr>
delete a group by `name` or by `nr`.
dump <file>
export a description (group name and frame layout) of the current group to `file`.
exec <command>
execute as shell command.
focus <left|right|up|down> or <lfocus|rfocus|ufocus|dfocus>
change focus to a frame in the specified direction.
height <relative|pixel>
resize frame vertically.
hook <on|off> <name> <command>
bind a Musca command to a named hook.
hsplit <relative|pixel>
split frame horizontally.
kill <number|name>
politely close the client window via a close event. When the optional
argument `number` or `name` is given, kill the associated window,
otherwise kill the current frame. Press again to forcibly kill it.
load <file>
import a description from `file` into the current group.
manage <on|off> <name>
(toggle) set whether the window class called `name` is managed or ignored.
move <name|nr>
move the current window to the group called `name` or to the group `nr`.
If it's an unknown group, automatically creates the group `name` and then
moves the current window to that group.
name <name>
rename the current group.
remove all other frames except the current one, resizing it to full screen.
pad <left> <right> <top> <bottom>
set the current group screen padding in pixels.
exit Musca.
raise <number|title>
raise and focus a window in the current group by number (order opened) or
remove the current frame and resize others to fill the gap.
resize <left|right|up|down>
resize the current frame in the specified direction.
run <file>
execute a file consisting of Musca commands. The file must contain
one command per line. Lines starting with hash *#* are comments and
blank lines are acceptable.
say <text>
display text via the method in the 'notify' setting.
screen <number>
switch to screen `number`. This is zero based, and should match the order
in which screens are defined in "xorg.conf".
set <setting> <value>
set a Musca variable. See SETTINGS for a list of variable names.
launch the dmenu shell command input.
show <settings|bindings|unmanaged|hooks|groups|frames|windows|aliases>
output a system table for diagnostic purposes.
shrink <number|title>
Minimize/Iconify (same thing in Musca) a window.
slide <left|right|up|down> or <lslide|rslide|uslide|dslide>
move current window into the frame to the left, right, up and down respectively.
stack <on|off|flip>
(toggle) switch the current group between `tiling` and `stacking` window modes.
swap <left|right|up|down> or <lswap|rswap|uswap|dswap>
swap current window with the contents of the frame to the left, right, up
and down respectively.
switch <window|group>
launch the dmenu window or group switcher.
revert the last frame layout change.
use <name|number|(other)|(prev)|(next)>
switch to a group called by its `name` or to a group by its `number`.
`name` has precedence over `number`. If it's an unknown group, automatically
creates the group `name` and then switch to that group.
When `(other)`, `(prev)` or `(next)`, switch to the previously focused, previous
or next group respectively.
vsplit <relative|pixel>
split frame vertically.
width <relative|pixel>
resize frame horizontally.


Any Musca command may be prefixed with "silent" to prevent any messages being sent to the notify setting. This is useful for scripting, to prevent popup window noise.


musca -c "silent show groups"

Relative values can be specified as a percentage or a fraction:


hsplit 2/3
hsplit 33%


Type: string
Default: Green

Border colour for focused `catchall` frames in tiling mode.

Type: string
Default: Dark Green

Border colour for unfocused `catchall` frames in tiling mode.

Type: string
Default: Red

Border colour for focused `dedicated` frames in tiling mode.

Type: string
Default: Dark Red

Border colour for unfocused `dedicated` frames in tiling mode.

Type: string
Default: Blue

Border colour for focused frames in tiling mode, and focused windows in stacking mode.

Type: string
Default: Dim Gray

Border colour for unfocused frames in tiling mode, and unfocused windows in stacking mode.

Type: integer
Default: 1

Width in pixels of frame borders in tiling mode, and window borders in stacking mode. The minimum value is 0, which makes frame borders invisible.

Type: integer
Default: 4096

Size in bytes of the allocated buffer for passing commands and results to and from "musca -c" and "musca -i".

Type: string
Default: "dmenu -i -b"

Command to run to launch 'dmenu' along with any customize appearance arguments. This can be replaced by another launcher so long as it accepts a list of \n terminated items on stdin and returns a single line on stdout.

Type: boolean
Default: 0

(toggle) Set to 1 to enable.

Type: integer
Default: 1

When set to "0", empty frames will stay empty until a window is manually selected. When set to "1", empty frames will automatically display the first available hidden window. When set to "2", empty frames will automatically display only windows previously displayed in this frame.

Type: integer
Default: 100

Minimum width and height in pixels of frames and managed windows.

Type: integer
Default: 20

Size in pixels of a frame resize step. Setting this smaller will make resizing operations smoother, but also slower and increase load.

Type: string
Default: current

Where focus should go when splitting a frame. When set to "current", focus remains to the current frame. When set to "new", the new frame receives the focus.

Type: boolean
Default: 0

When set to "1" and navigating away from an empty group, automatically drop this group.

Type: string
Default: "echo `cat`"

The command to run to send the user a message. By default Musca just writes to stdout.

Type: integer
Default: 4096

Size in bytes of the allocated buffer for passing messages to the command defined in the 'notify' setting.

Type: string
Default: "$MUSCA -i"

The command to run when the user has entered a Musca command via 'dmenu'.

Type: string
Default: "sed 's/^/exec /' | $MUSCA -i"

The command to run when the user has entered a shell command via 'dmenu'.

Type: string
Default: Mod4

The modifier key to use in `stacking` mode, along with mouse buttons 1 and 3, to move and resize windows respectively.

Type: string
Default: ~/.musca_start

(optional) Path to a file containing Musca commands to run at start up. The default setting is relative to the working directory, i.e., Musca will use "$HOME/.musca_start" only if Musca is started from $HOME, which is the usual method for login managers. The file must contain one command per line. Lines starting with hash *#* are comments and blank lines are acceptable.

Type: string
Default: "sed 's/^/use /' | $MUSCA -i"

The command to run once the user has selected a group name from 'dmenu'.

Type: string
Default: "sed 's/^/raise /' | $MUSCA -i"

The command to run once the user has selected a window number and name from 'dmenu'.

Type: boolean
Default: 1

(toggle) Set to 0 to prevent new windows from taking the input focus.

Type: string
Default: current

When set to "current", new windows always open in the currently focused frame. When set to "empty", new windows will try to find an empty frame to use.

Type: boolean
Default: 1

(toggle) Set to 0 to disable size hints checks for new windows. This can still be overridden on a per client basis using the client command.


Default Keyboard commands


hsplit 1/2


vsplit 1/2










switch window


switch group






dedicate flip


catchall flip




stack flip


focus left


focus right


focus up


focus down


use (next)


use (prev)


screen (next)


resize left


resize right


resize up


resize down


swap left


swap right


swap up


swap down

Mouse commands


Moves a window in stacking mode.


Resizes a window in stacking mode.


Executing Musca commands can optionally trigger a hook command. This can be useful for chaining Musca commands together or firing off scripts on certain events. For example, set default new group padding by hooking into the add command:

hook on ^add pad 0 0 0 26

Or, attach to multiple commands:

hook on ^(add|use) pad 0 0 0 26

For now, only Musca commands trigger hooks. In the future this may be extended to add hooks to X events.

Stacking Mode

Stacking window management mode is available at the window group level, on a group by group basis. Select the group you wish to make stacking, and press 'Modifier+s' or run the command 'stack on'. Any frames in the group will disappear. Other groups will not be affected.

Floating windows can be moved using 'Modifier+Mouse1', i.e., hold down the modifier key and click the left mouse button on the window and dragging the mouse. Floating windows can be resized using 'Modifier+Mouse3' in the same fashion. Click-to-focus still works.

Most of the frame manipulation related key combinations and commands are disabled in stacking mode. Note: there is no way to float specific windows while in tiling mode.

To switch the group back to tiling mode, press 'Modifier+s' again or run the command 'stack off'. The group frames will be recreated as they were before the mode change.

Make Musca ignore windows

In config.h there is an unmanaged_windows[] list of WM_CLASS names:

char *unmanaged_windows[] = { "trayer", "Xmessage", "Conky" };

Check out the xprop utility to find class names. Either change unmanaged_windows[] and recompile, or do on the fly in .musca_start with the 'manage' command. Note that any manage setting only takes effect for subsequently opened windows.

See Also

dmenu(1), wmctrl(1)


Sean Pringle


April 10, 2009 Musca Users Manual