• Website
• Repository
• Report issues
• Trello board

BiscuitWM is an X11 window manager based on the Python version of TinyWM by Nick Welch and the xpywm window manager by Hiroyuki Ohsaki. The intent of this window manager project is largely to expand my understanding of the X11 libraries via Python.

Development and testing is being done in a Debian 11 virtual machine with Python 3.9 as the main Python interpreter.

WARNING: This project is still in alpha. It is not recommended to run BiscuitWM on a production machine without using Xephyr to run an embedded X session!

Before running BiscuitWM, you must have the python-xlib, x11util, perlcompat, and ewmh libraries installed. To do so, use the pip Python package manager to install it:

cd /path/to/project

sudo apt update
sudo apt install python3 python3-pip

pip3 install -r requirements.txt

To install BiscuitWM on your system, run the setup.sh as sudo (as we need to chmod the scripts to run the Python files):

sudo sh scripts/setup.sh

To run the uninstall script, run the purge.sh script as sudo as well:

sudo sh scripts/purge.sh

At the moment, BiscuitWM follows the hybrid keyboard and mouse driven interaction from TinyWM. Future iterations will seek to add titlebars to allow for mouse-first interactivity.

Note that whichever window your cursor is hovering over will be the window with input focus (and will also be raised). Future iterations will require the window to be raised by clicking on the window.

WARNING: As of 17 September 2021, keyboard shortcuts are reportedly unresponsive. A solution for this issue is currently being worked on. See issue ticket.

• Alt + Left Click and drag: Move window
• Alt + Right Click and drag: Resize window
• Alt + Q: Close the currently-focused window

• Alt + -: Move window to center of display
• Alt + =: Maximize currently-focused window
• Alt + [: Fill left-side of the screen with currently-focused window
• Alt + ]: Fill right-side of the screen with currently-focused window
• Alt + \: Fill top of the screen with currently-focused window
• Alt + /: Fill bottom of the screen with currently-focused window

• Alt + Tab: Cycle through all windows
• Alt + Left Click on deskbar: Cycle through all windows
• Alt + Right Click on deskbar: Show number of windows

• Alt + Space: Enables launcher mode in the top bar
• Return: Enter command and exit top bar launcher
• Esc: Exit launcher mode

• Alt + X: Launch a new terminal window
• Alt + Esc: Exit BiscuitWM session

BiscuitWM can read a JSON file (stored at /etc/biscuitwm/biscuitwm.json) for options such as debug output, window placement, window decorations, etc.

Instead of constantly logging off, switching the Xsession, then logging in again to test, it will be easier to just run an embedded Xsession within your current session. To do this, install the Xephyr package (xserver-xephyr).

Open a terminal and run:

Xephyr -br -ac -noreset -screen 1024x780 :1 &

You should then see a Xephyr window popup (nothing will be visible since there is no window manager assigned). Then enter:

DISPLAY=:1

...to send commands to this new Xephyr window. Then start the BiscuitWM session:

biscuitwm-session

Once you're done with testing, you may want to just reuse the same terminal for local commands. Thus, enter this command:

DISPLAY=:0

...to resume sending commands to your current Xsession.

See the acknowledgements section of the website for more details.

• BiscuitWM is based off the work of Nick Welch (2005, 2011) and Hiroyuki Ohsaki (2019-Present). It also uses a code snippet by Rodrigo Silva (2016) and integrates a project by vulkd (2017, 2019).
• The project's logo uses a modified version of this image.