Warning

This project is a work in progress. The first stable, feature-complete release will be version 1.0.0. As such, it is advised that you do not use this as your daily driver unless you are willing to encounter some paper cuts along the way. If you are willing to lend your time to find bugs, fix bugs, or submit proposals for new features, it would be greatly appreciated.

About

miracle-wm is a Wayland compositor based on Mir. It features a tiling window manager at its core, very much in the style of i3 and sway. The intention is to build a compositor that is flashier and more feature-rich than either of those compositors, like swayfx.

Please see the roadmap document for the current status and direction of the project.

Install

# snap
sudo snap install miracle-wm --classic

# deb (jammy, mantic, or noble)
sudo add-apt-repository ppa:matthew-kosarek/miracle-wm
sudo apt update
sudo apt install miracle-wm

Or for the nightly build:

sudo snap install miracle-wm --classic --edge

Note

While the project is only built as a snap at this moment, I am not allergic to other packaging formats, just perhaps too lazy to implement them at this moment. I will happily accept contributions in this domain.

Building

From Source:

git clone https://github.com/mattkae/miracle-wm.git
cd miracle-wm

cmake -Bbuild
cmake --build build
WAYLAND_DISPLAY=wayland-98 ./build/bin/miracle-wm

Snap:

cd miracle-wm
snapcraft
sudo snap install --dangerous --classic miracle-wm_*.snap

Running

On login:

Once installed, you may select the "Miracle" option from your display manager before you login (e.g. GDM or LightDM). In most environments, this presents itself as a little "settings" button after you select your name.

Note that if you installed the snap, the option may read "Miracle (snap)" to distinguish it from the binary version.

Hosted:

To run the window manager as a window on your current desktop session, simply run:

WAYLAND_DISPLAY=wayland-98 miracle-wm

Note that this is only useful if you want to test-drive the window manager or do some development on it for yourself.

Usage

See the user guide for info on how to use miracle-wm.