miracle-wm: a tiling Wayland compositor with a WebAssembly plugin system

What miracle-wm is and what it sits on

miracle-wm is described as a hackable, stylish and modern Wayland compositor built on Mir. The README is careful about the lineage, and it matters: it brings the keyboard-driven efficiency of i3 and Sway to a richer and more extensible experience, with smooth animations, a WebAssembly plugin system and a hot-reloadable configuration.

Building on Mir is the decision that shapes everything else about the project. Mir is a display server, and a compositor built on one inherits its input handling, its rendering path and its session management rather than implementing them. The consequence for a user is a compositor that sits in a different place from a pure Wayland library like wlroots based ones. The consequence for a developer is that the surface area of the codebase is bounded by what Mir exposes.

The composition model itself is a hybrid, and the feature list states it plainly. You can mix manual tiling with floating windows and with entirely custom window management rules, which is a wider range than the usual choice between a tiling model and a floating model. The README also claims multi-monitor support with independent workspaces across outputs, fully configurable, and accessibility features including a magnifier, slow keys, sticky keys and cursor configuration.

The repository layout suggests a project with several distinct surfaces rather than a single binary. There is src/ and include/ for the compositor, miracle-wm-c/ and miracle-plugin-rs/ for the C and Rust plugin sides, protocols/ for the Wayland protocol definitions, shaders/ for the rendering, session/ for session management, miraclemsg/ for the message utility, debug-overlay/, error-reporter/, tools/, tests/ and e2e/ for the test suites, and a wiki/ directory that holds the documentation.

The plugin system and what it changes about extending a compositor

The WebAssembly plugin system is the feature that distinguishes this project from the tiling compositors it draws on, and the README describes it in one line: extend and override core behavior without touching a line of C++.

That is a real architectural statement rather than a slogan. A compositor that ships a scripting language changes what a user can do with a configuration problem. In a compositor without one, the answer is to read the source and compile it. Here the answer is to write a plugin, and the repository carries two plugin directories, miracle-plugin-rs/ and miracle-wm-c/, which suggests that Rust and C are both supported paths into the same plugin interface.

The plugin API has its own documentation site at docs.miracle-wm.org, separate from the wiki, which is a sensible split since the wiki covers using and building the compositor while the API reference is for plugin authors.

The other feature that changes the shape of day to day use is the hot-reloadable configuration. The README lists apply config changes instantly as a built-in capability, which means the feedback loop between editing a config and seeing the result does not involve a compositor restart. For a keyboard-driven workflow where the config is where most of the personalisation lives, that is the feature that determines whether the system is pleasant to tune.

The i3 and Sway compatible IPC is the third piece, and it is the one that makes miracle-wm a citizen of the wider tiling ecosystem. The README says it works with swaymsg, Waybar and similar tools, which is achieved by speaking the same protocol rather than by reimplementing a panel.

Where the documentation lives and how to get started

The README is short, and it says where everything else is in a single sentence: installation instructions, build instructions and a full roadmap live at wiki.miracle-wm.org.

So the getting started path is a wiki rather than a section of the repository, and that has a practical implication. There is no command sequence in the README to copy, and the build is from source with the project's own toolchain, which for a compositor with shaders, a protocol directory and a Mir dependency is a real build rather than a package install.

The repository does contain a wiki/ directory, so the documentation source is versioned alongside the code, which is better than a wiki that drifts. There is also a RELEASING.md file at the root, which is a good sign about the release process, and a debian/ directory and a snap/ directory, so there is packaging for at least two distributions.

The default branch is develop, which is worth knowing before you clone. The releases are tagged from that branch, and the recent release list shows v0.11.2 from 2026-09-26, v0.11.1 from 2026-09-22 and v0.11.0 from 2026-09-16. Three releases in ten days is a fast cadence for a compositor, and it is a reminder that a 0.x version number here describes a project in active development rather than an unstable one.

The last push was on 2026-10-20, so the code is changing daily, and the wiki and the API docs are where you will find the current state of any given feature.

Where miracle-wm is the wrong tool

The first limitation is the absence of a graphical settings application. Everything is configuration, and the configuration is a document you edit, with the wiki as the manual. That is the i3 and Sway model and it is a deliberate choice, but a user arriving from a desktop environment will find the first hour slower than they expect.

The second is the hardware and driver surface. A compositor built on a display server, running Wayland with its own shaders and its own input handling, is exposed to the parts of the Linux graphics stack that are still uneven. The README's feature list is long and confident, and it says nothing about which GPUs are known to work, so a prospective user has to find that out themselves in the wiki or in the tracker.

The third is that the plugin system raises the bar for maintenance. A WebAssembly plugin API is a commitment: the ABI between the host and the plugin has to stay stable across versions, and a compositor that ships one is making a promise about the future. A user who writes plugins against v0.11 is betting that the interface survives the next major version, which the 0.x version number does not promise.

The fourth is the size of the codebase for a hackable project. The source tree includes a debug overlay, an error reporter, a session manager, a message tool, protocols, shaders, tools, unit tests and an e2e suite. That is a well-organised project rather than a simple one, and hacking on it means reading a lot of someone else's code first.

The fifth is the upstream dependency. Mir is the base, so the pace of Mir's own development and the stability of its Wayland support set the ceiling on what miracle-wm can offer.

How miracle-wm compares with Sway, Hyprland and Mir itself

Sway is the comparison that matters most, because miracle-wm explicitly follows the i3 and Sway model. The difference in approach is that Sway is built on wlroots and has no scripting language, so a Sway user extends it with shell scripts driven by keybindings, and the shell is the extension mechanism. miracle-wm replaces that with a WebAssembly plugin interface that can override core compositor behaviour, which is a deeper hook than a script that runs a command.

The cost of that deeper hook is a stronger coupling. A shell script calls the same IPC that any client can call, so it cannot break the compositor, while a plugin that overrides core behaviour can. That is the trade the project is making, and it is why the plugin API has its own documentation site.

Hyprland is the other comparison, and the difference is scope. Hyprland is a standalone Wayland compositor with a large configuration surface of its own, animations as a first-class feature and a plugin system that is based on shared libraries loaded into the compositor process, with the usual consequence that plugins are tied to the compositor's build. miracle-wm's WebAssembly plugins are language-agnostic and sandboxed by construction, which is a different answer to the same problem.

Mir itself is the third. Mir is a display server, so the difference is that a display server is a lower layer than a compositor, and a project building on it inherits the display server's responsibilities. miracle-wm is a compositor, which is what a user installs and what a Sway user would recognise as a comparable thing.

The fourth comparison is with a tiling window manager on X11, which for a user starting today is the alternative that needs no new session. The trade is the usual one: a modern compositor with animations and a plugin system against the compatibility and stability of the X11 stack.

Licence, community and what to check before installing

The licence field on the repository records GPL-3.0, with the LICENSE file at the root. A copyleft licence is the expected choice for a compositor, and it is the one that makes the hackable premise work in the way the README describes, since a modified compositor that is distributed has to carry the same licence.

The community channels are the usual two for a Linux desktop project, with the README pointing at a Matrix room, #miracle-wm on matrix.org, and a Discord server. Both are linked from the top of the README, and the README says questions, ideas and contributions are welcome in either.

Four things are worth checking before installing, and all four are answered in the wiki rather than here.

Which graphics hardware is known to work, since the README does not say and a compositor that fails to start is not a learning experience. Whether the Mir dependency builds cleanly on your distribution, since the build instructions are in the wiki and the dependency chain goes deeper than a single library. Which version to take, because the default branch is develop and the tags are the 0.11 series, so a distribution package and the git checkout are likely to be on different code. And what the roadmap says about the features you actually need, because the feature list describes a target as much as a present.

The last point is the one that separates a good first impression from a bad one. A compositor with animations, a plugin system and accessibility support is a serious piece of work, but the honest test of a 0.x desktop is whether the things you use daily work without configuration archaeology, and the wiki is where that answer lives.

Editorial conclusion

miracle-wm suits someone who wants an i3-style keyboard workflow on Wayland and is willing to read a wiki and configure the compositor by hand, and who wants to extend it without compiling C++. It is the wrong choice for a user who expects a settings GUI, a one-line install or a driver-free desktop session, since the getting started material is in a wiki and the build is from source. Before adopting it, read the roadmap at wiki.miracle-wm.org, because the feature list in the README describes what exists rather than what is finished, and check the protocol directory in the repository, since the i3 and Sway compatible IPC is what lets tools like swaymsg and Waybar work unchanged.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. miracle-wm-org/miracle-wm on GitHub
3. Project website
4. README
5. Releases