Skip to content

Features#

A tour of what margo ships. margo is a Rust-native Wayland compositor plus a complete first-party desktop stack — there is no GNOME/KDE underneath. This page is the map; each section links to the detailed guide.

Compositor#

The Smithay-based tiling compositor, in the dwl/mango tradition — tags instead of workspaces, driven by mctl.

  • 10 tiling layouts — tile, scroller (PaperWM-style, the default), grid, monocle, deck, dwindle, and more; each tag remembers its own. Set with setlayout <name>, cycle with switch_layout. See Configuration → Layouts.
  • Floating layout — setlayout floating (or taglayout / default_layout) gives a classic stacking desktop: the tag's windows auto-float with a cascade and re-tile when you switch back to a tiling layout.
  • Mosaic layout — setlayout mosaic, GNOME's content-aware self-arranging concept: windows keep their own size (honouring each app's real min/max hints) instead of a fixed grid, reflowing automatically as you open and close them. Drag one window onto another to swap places (drag_tile_to_tile); a window that no longer fits even at its own minimum size moves itself to the first empty tag (mosaic_auto_overflow_tag), or, if you'd rather it stay put, shrinks to a small always-visible "peek" in the corner instead (mosaic_overflow_stack).
  • Dispatch actions — the full keybind/IPC verb catalogue (focus, move, resize, scratchpad, overview, summon/focusapp, …). Always-current list: mctl actions --verbose.
  • Animations — spring / bezier window + layer motion, pre-baked into LUTs.
  • Twilight — built-in blue-light filter with geo/schedule phases (mctl twilight).
  • Built-in xdg-desktop-portal — native ScreenCast backend (window + monitor share). See Built-in portal.
  • HDR + colour management — see HDR + colour management.
  • XWayland, output hotplug, and a Wayland protocol matrix / comparison against the other compositors.
  • Window / tag / layer rules — PCRE2-style regex matching to place, float, size, or tag clients. See Configuration → rules.
  • Scripting engine — Rhai scripting hooks. See Scripting and the design notes.

Desktop shell (mshell)#

The GTK4 + relm4 shell hosting the bars, menus, settings, and dashboard.

  • Bars + widgets — top/bottom bars with 50+ pills. Full reference: Bar widgets.
  • mdash dashboard — greeting, calendar, weather, media, quick-settings tiles, menu-shortcut grid (mshellctl menu mdash).
  • Control Center — quick-settings menu (sliders + toggle grid).
  • Settings — in-shell GTK settings for the whole stack (Appearance, Bar, Widgets, Network, Bluetooth, Power, Sound, Animations, Keybinds, Calendar, AI, Toasts, and more).
  • Notifications — first-party center with history, inline reply, sounds, progress, and Do Not Disturb.
  • Toasts — corner cards announcing state changes (power, audio device, network, Bluetooth, VPN, power profile, keyboard layout, DND, Game Mode, …), separate from app notifications. Per-event switches in Settings → Toasts; mshellctl toast is the notify-send equivalent.
  • OSD — volume / brightness value pulses.
  • Launcher — app / calc / ssh / sysinfo / emoji providers.
  • Material You theming — matugen palette extraction from the wallpaper, applied across the shell, the compositor border, and the login screen.
  • Game Mode — one toggle drops compositor effects, enables Do Not Disturb, and holds the idle inhibitor (mshellctl gamemode toggle).
  • WASM plugins — capability-sandboxed plugin runtime (wasmtime). See WASM plugins.
  • Music player (mtune) — a folder-first player with its own bar pill + menu (seek bar, transport, speed, playlists), MPRIS + tray, and a mshellctl mtune CLI. See Companion tools → mtune.

Companion binaries#

Standalone tools that ship with margo. Full guide: Companion tools.

Tool Role
mctl Compositor IPC client — control + introspect margo.
mshellctl Shell IPC client — toggle menus, query state, media control, mpv companion + video wallpaper, mtune.
mvpn Mullvad VPN control (CLI + GTK panel).
mcal Calendar — local + remote ICS (read-only), CLI + Settings → Calendar.
mtune Folder-first music player — GTK4 + GStreamer, MPRIS, tray, own bar pill + menu.
mkeys On-screen keyboard.
mpicker Screen colour picker.
mscreenshot Screenshot CLI (region / window / output).
mpower Automatic power-profile manager (CPU + AC/battery aware).
mlock Lock screen (PAM + ext-session-lock-v1).
mlogind Login / display manager (PAM); GTK4 multi-monitor greeter by default.
mgreet GTK4 graphical login greeter for mlogind — per-output, matugen-themed.
mlayout Saved tiling-layout snapshots.
mdots Declarative Arch package + dotfiles manager (pacman/AUR/Flatpak/Nix, SOPS/age secrets).
start-margo Hang-aware session supervisor (systemd watchdog, restart backoff).

Configuration & IPC#

  • Configuration — the config.conf guide (layouts, dispatch actions, keybindings, gestures, rules) and the full annotated reference.
  • IPC — the mctl ↔ margo Unix socket (get / watch / dispatch) and the mshellctl ↔ mshell D-Bus surface.
  • Scripting — automating the desktop.
  • Install — packaged installer + manual build.

The website (https://kenanpelit.github.io/margo/) is the canonical, always-current documentation.