A Wayland-native screen magnifier and cursor spotlight tool for streamers, built for Wayland compositors supporting the required wlroots protocols. Miru is primarily developed and tested on Niri.

Inspired by boomer, but for Wayland — written in C, keybind-driven, no GUI, no mouse-required config.

See Roadmap for the full picture.

• What it does
• Why
• Performance
• A note on global hotkeys
• Requirements
• Installing
• Building
• Running
• Man pages
• Configuration
• Project structure
• Roadmap
• Similar tools
• License
• Contributing

• Magnifier mode — press a key, the screen freezes into a zoomed-in fullscreen view centered on your cursor (or the last known pointer position from a previous session in the same daemon run). Move the mouse to pan, scroll or press +/- to adjust zoom, use arrow keys or WASD to pan by keyboard, press Esc (or the toggle key again) to exit. Like boomer, but native Wayland.

  While active:

  • Tab toggles Cursor Highlight — darkening everything except a soft-edged circle that follows the real pointer (absolute tracking), even when zoomed. Configurable via [spotlight]. Radius can be adjusted live with Shift+Plus/Minus or Ctrl+scroll. Entry/exit of the highlight is animated (spotlight.animation_speed).
  • Shift+A toggles Annotate mode — pan freezes and you can draw presentation shapes on the frozen frame (arrows and rectangles). See controls below.
  • Shift+H or ? toggles an on-screen help panel listing the current keybinds (Esc closes help first, then exits the magnifier).

  Cursor Highlight, annotations, and help only work inside an active Magnifier session; the desktop underneath stays frozen/grabbed while the overlay is on. Built and working now.

• Loupe Mode: miructl loupe freezes the screen the same way as miructl toggle, then lets you drag a rectangle over an area. After release, only the selected region is zoomed in a fixed-size window that follows the cursor; the rest of the frame stays at 1x. Scroll to change loupe zoom. Toggle again (or quit) to exit. Separate from the above Magnifier Mode. Requires a separate compositor keybind.

• Spotlight mode — a fully independent, click-through overlay that darkens the whole screen except a cursor-tracking circle, while you keep working normally underneath — no freeze, no input grab, usable during normal desktop work rather than only inside a Magnifier session. This is a different, harder problem than Cursor Highlight above: it needs cursor tracking without stealing pointer/keyboard focus, which Cursor Highlight sidesteps entirely by already owning input while Magnifier is active. Not built yet.

Most screen magnifiers either don't exist for Wayland, or route through XWayland with visible artifacts and no compositor integration. Miru uses Wayland protocols directly, currently relying on wlr-layer-shell for its overlay and wlr-screencopy for screen capture. The overlay itself is rendered with OpenGL ES 2 via EGL.

Because there's no continuous re-capture while the overlay is inactive (see Setting up a keybind below for why), miru-daemon sits completely idle — blocked in poll() waiting for either a Wayland event or a toggle command — for as long as you're not actively using it. In practice this means ~0% CPU usage at rest:

Miru is toggled via a compositor-level keybind (see Setting up a keybind below), not an in-app global hotkey — and this is deliberate, not a missing feature. Wayland's security model doesn't allow any client to listen for keypresses while it isn't focused; only the compositor itself has that privileged access, which is exactly why every Wayland compositor provides some way to bind a key to a command (a config file, or a GUI).

Routing through the compositor is the correct, secure way to do this — the alternative (a client reading raw kernel input events directly, bypassing Wayland's input model) means running with elevated device permissions and having the daemon read every keystroke on your system at all times just to catch one hotkey, which is a meaningfully bigger trust ask than this project wants to make for a screen-zoom tool.

• A Wayland compositor implementing wlr-layer-shell-unstable-v1 and wlr-screencopy-unstable-v1
• wayland-client, wayland-protocols, wayland-scanner (pacman: wayland, wayland-protocols)
• EGL + OpenGL ES 2 development packages
• CMake ≥ 3.20, Ninja (optional)
• A C11 compiler

Miru currently requires a compositor that exposes both wlr-layer-shell and wlr-screencopy.

• Niri — supported and used for development/testing
• Sway — supported; both required protocols are core to the wlroots ecosystem Sway is built on
• Hyprland — supported by the required wlroots protocols
• Mango — supported if the required protocols are exposed
• Nauka — supported and tested by @shadowash8 (https://github.com/shadowash8/nauka)
• GNOME / Mutter — not supported
• KDE Plasma / KWin — not supported

Support for compositors without these protocols may be added later through alternative capture and overlay mechanisms.

# latest tagged release
paru -S miru-zoom
# or track the latest commit on main
paru -S miru-zoom-git

Substitute your AUR helper of choice — yay, paru, or a manual makepkg -si against the PKGBUILD.

Miru is packaged in nixpkgs (attribute miru). Prefer that over the project flake when you want a normal channel/package install.

Run without installing (unstable channel):

nix shell nixpkgs/nixos-unstable#miru -c miru-daemon
# control client from the same package:
nix shell nixpkgs/nixos-unstable#miru -c miructl toggle

Classic nix-shell:

nix-shell -p miru -I nixpkgs=channel:nixos-unstable --run miru-daemon

Install to your user profile:

nix profile install nixpkgs/nixos-unstable#miru
# or: nix-env -iA nixpkgs.miru -f channel:nixos-unstable

NixOS — if your system follows unstable:

environment.systemPackages = with pkgs; [
  miru
];

On stable, pull only this package from unstable:

{ config, pkgs, ... }:
let
  unstable = import <nixos-unstable> { config = config.nixpkgs.config; };
in
{
  environment.systemPackages = [ unstable.miru ];
}

sudo nix-channel --add https://nixos.org/channels/nixos-unstable nixos-unstable
sudo nix-channel --update

Development / bleeding edge (optional project flake):

nix run git+https://codeberg.org/Vaishnav-Sabari-Girish/miru
nix develop git+https://codeberg.org/Vaishnav-Sabari-Girish/miru

brew tap Vaishnav-Sabari-Girish/tap
brew install miru

See Building below.

# Using Ninja
cmake -S . -B build -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
# Using Make
cmake -S . -B build -G "Unix Makefiles" -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

Then run:

cmake --build build

Or with Grimoire:

grim cast build # Uses make to build by default

This builds two binaries: miru-daemon (the actual Wayland client) and miructl (a tiny, Wayland-independent socket client used to control it).

To install miru-daemon and miructl to ~/.local/bin:

cmake --install build

Or with Grimoire, which also configures CMAKE_INSTALL_PREFIX for you:

grim cast install

You can run miru-daemon directly in the foreground, or set it up as a systemd user service so it starts automatically with your graphical session.

./build/miru-daemon
# or
grim cast run-daemon

Create ~/.config/systemd/user/miru.service:

[Unit]
Description=Miru Zooming Daemon
PartOf=graphical-session.target
After=graphical-session.target
ConditionEnvironment=WAYLAND_DISPLAY
ConditionPathExists=%h/.local/bin/miru-daemon

[Service]
ExecStart=%h/.local/bin/miru-daemon
Restart=on-failure
RestartSec=1

[Install]
WantedBy=graphical-session.target

This assumes miru-daemon has been installed to ~/.local/bin (see Installing the built binaries above) — adjust ExecStart/ConditionPathExists if yours lives elsewhere.

Then enable and start it:

systemctl --user enable --now miru.service

Either way, once running, miru-daemon connects to the compositor, logs every advertised protocol, opens a Unix socket at $XDG_RUNTIME_DIR/miru.sock, and then idles — no overlay is shown until told to toggle. Nothing else happens until a toggle command arrives (see Performance above for what that idling actually costs).

Toggle the overlay on/off:

./build/miru-daemon --version # prints version info + an ASCII logo, exits immediately
./build/miructl toggle        # freezes + zooms the screen / returns it to normal
./build/miructl loupe         # region loupe: drag a rectangle, then zoom that region only
./build/miructl quit          # tells the daemon to shut down

miru-daemon and miructl each have their own man page. How you access them depends on how you installed Miru:

• Installed via miru-zoom-git (AUR), cmake --install build, or grim cast build/grim cast install — no extra step, man miru-daemon and man miructl work immediately.
• Homebrew — not wired up yet, coming soon.
• Built from source but not installed to $PATH — point man at the page directly from the repo root:

man ./miru-daemon.1
man ./miructl.1

Miru uses a TOML configuration file located at:

$XDG_CONFIG_HOME/miru/config.toml

If XDG_CONFIG_HOME is not set, Miru follows the XDG fallback and uses:

$HOME/.config/miru/config.toml

The directory and default configuration file are created automatically on first launch.

The default configuration is:

[zoom]
factor = 2.0
increment = 0.25
max_factor = 10.0
smooth = false

[spotlight]
radius = 250
dim = 0.65
softness = 20
animation_speed = 14.0
radius_step = 20.0

[general]
show_cursor = true

The currently active options are:

• zoom.factor — initial zoom level applied on each toggle-on. Must be at least 1.0.
• zoom.increment — amount the zoom changes per key/scroll input. Must be greater than 0.
• zoom.max_factor — maximum zoom level. Must be at least 1.0.
• zoom.smooth — when true, zoom level and pan position are smoothly interpolated toward their targets instead of snapping.
• spotlight.radius — radius, in pixels, of the fully-bright circle around the cursor.
• spotlight.dim — how much darker the dimmed area gets, from 0.0 (no effect) to 1.0 (fully black).
• spotlight.softness — width, in pixels, of the feathered transition between the bright circle and the dimmed area.
• spotlight.animation_speed — how quickly Cursor Highlight radius/dim ease in and out when toggling Tab. Higher is faster.
• spotlight.radius_step — step size when adjusting the highlight radius with Shift+Plus/Minus or Ctrl+scroll.
• general.show_cursor — when false, hides the hardware cursor while the overlay is active (restoring a themed cursor when turning it back on may be limited depending on the compositor).

Invalid numeric values, including malformed, overflowing, non-finite, and non-positive values where applicable, fall back to safe defaults. zoom.factor is clamped to zoom.max_factor when necessary.

The config file is watched while miru-daemon is running — saving changes takes effect immediately, no restart needed. zoom.max_factor, zoom.smooth and every [spotlight] value update live, including on an already-active overlay; zoom.factor (the initial zoom on toggle-on) takes effect starting with the next toggle, since retroactively snapping an in-progress session to a different zoom level would be jarring rather than useful.

Additional input, zoom and texture-upload diagnostics can be enabled by setting MIRU_DEBUG to a non-zero value:

MIRU_DEBUG=1 ./build/miru-daemon

You'll want this bound to a key rather than run manually. Each supported compositor has its own way to bind a command to a key:

Niri — ~/.config/niri/config.kdl:

Mod+Z hotkey-overlay-title="toggle miru" { spawn-sh "/path/to/miru/build/miructl toggle"; }
Mod+Alt+Z hotkey-overlay-title="toggle miru loupe" { spawn-sh "/path/to/miru/build/miructl loupe"; }

Hyprland — ~/.config/hypr/hyprland.lua:

hl.bind("SUPER + Z", hl.dsp.exec_cmd("/path/to/miru/build/miructl toggle"))
hl.bind("SUPER + ALT + Z", hl.dsp.exec_cmd("/path/to/miru/build/miructl loupe"))

Sway — ~/.config/sway/config:

bindsym $mod+z exec /path/to/miru/build/miructl toggle
bindsym $mod+alt+z exec /path/to/miru/build/miructl loupe

Mango — ~/.config/mango/config.conf:

bind=SUPER,Z,spawn,/path/to/miru/build/miructl toggle
bind=SUPER,ALT,Z,spawn,/path/to/miru/build/miructl loupe

Nauka — ~/.config/nauka/nauka.con:

keybind super z run "/path/

Read the rest on GitHub