Home Screen:

Lock Screen:

Quick Start

curl -fsSL https://raw.githubusercontent.com/S4NKALP/Modus/macos/install.sh -o install.sh && bash install.sh

The interactive installer handles dependencies, builds C-extensions, and configures Hyprland.

Manual Installation

Click to expand manual install steps

1. Install dependencies:

   paru -S uv fabric-cli-git uwsm cliphist slurp grim swappy wl-clipboard wtype libnotify matugen hypridle hyprsunset hyprpicker hyprshot gtk-session-lock awww otf-apple-sf-pro webp-pixbuf-loader cinnamon-desktop libmediaart acpi brightnessctl power-profiles-daemon at-spi2-core networkmanager network-manager-applet blueman pipewire libpulse gcc make pkgconf meson ninja wayland-protocols gobject-introspection gtk-layer-shell librsvg libqalculate appmenu-gtk-module libdbusmenu-gtk3 libdbusmenu-qt5 pciutils wf-recorder ffmpeg --needed

2. Clone and sync:

   git clone https://github.com/S4NKALP/Modus ~/.config/Modus
   cd~/.config/Modus
   uv sync

3. Build App Switcher backend:

   cd src/window/switcher/app-capture
   meson setup builddir
   meson compile -C builddir

4. Build Global Menu shim:

   cd src/window/globalmenu
   gcc -shared -fPIC -O2 -o libmenu_button_shim.so libmenu_button_shim.c $(pkg-config --cflags --libs gtk+-3.0) -ldl

5. Start Modus:

   cd~/.config/Modus
   uv run start

Post Installation

• Install recommended Icon theme, GTK theme, and Cursor theme
• Source config/hypr/modus.lua in your Hyprland config
• Lock screen bind: set to uv run lock

Keybinds

Key	Action
Super + D	Spotlight search
Super + E	Emoji picker
Super + V	Clipboard history
Super + W	Wallpaper browser
Super + I	Settings
Super + L	Lock screen
Super + Z	Screencapture toggle
Super + S	Screenshot region
Alt + Tab	Window switcher
Alt + Space	Keyboard layout switch
Super + Shift + R	Reload Modus
Super + Shift + Y	Reload CSS
Alt + Shift + W	Random wallpaper

Configuration

Three TOML files in config/:

File	Purpose	Reload
config.toml	Main settings (features, widgets, paths)	Restart
mods.toml	Custom panel buttons	Instant
dock.toml	Pinned dock apps	Restart

Settings are organized into sections: [general], [dock], [panel], [switcher], [notification].

You can also toggle most settings from the Settings window (Super + I).

See Configuration Guide for full reference.

Desktop Widgets

Drop a .py file in config/desktop/ and it appears on your desktop instantly:

cp examples/desktop/example.py config/desktop/example.py

Edit positions in config/desktop.toml or drag widgets in edit mode (right-click → Edit Widgets).

nvim config/desktop/example.py # live reload, no restart needed
rm config/desktop/example.py # widget disappears within 2s

See Desktop Widgets Guide for full docs and examples.

Documentation

Note: These docs were written with the assistance of LLM tools. Some phrasing may reflect that.

Doc	What's inside
Installation Guide	Automated & manual install, dependencies
Configuration Guide	config.toml, mods.toml, dock.toml, keybinds
Styling Guide	Matugen colors, CSS customization
Architecture Overview	App Switcher C-backend, Spotlight engine, Services
Spotlight Plugins	Install/customize plugins, write your own
Desktop Widgets	Custom desktop widgets, user widget system
FAQs & Tips	Troubleshooting, shortcuts, live reload

Custom Mods

Define panel buttons in config/mods.toml:

[Mods.terminal]
icon = "terminal.svg"icon-size = 16order = 1on-clicked = "kitty"

• icon — SVG filename in src/assets/icons/
• icon-size — defaults to 16
• order — button position (lower = first)
• on-clicked — shell command on click
• on-left, on-middle, on-right — per-mouse-button commands
• options — dropdown menu entries (each with label + on-clicked)
• Live reload — edits apply instantly

Spotlight Plugins

Drop a .py file in config/plugins/ and it works instantly:

cp examples/plugins/hello.py config/plugins/hello.py
# Hit Super+D, type "hi" — greeting appears

Plugin development with hot reload:

nvim config/plugins/hello.py
fabric-cli exec modus 'deep_reload hello'# no restart needed

See Spotlight Plugins for full docs and examples.

Global Menu Compatibility

Modus injects libmenu_button_shim.so only into GTK3 apps launched through Modus (dock, spotlight, panel). GTK4 apps are never touched.

For terminal-launched GTK3 apps, use a wrapper:

#!/usr/bin/env bash
SHIM=~/.config/Modus/src/window/globalmenu/libmenu_button_shim.so
BIN="$(command -v "$1")"if [[ -n"$BIN" ]] && readelf -d "$BIN"2>/dev/null | grep -q 'libgtk-3\.so\.0';then
LD_PRELOAD="$SHIM""$@"else"$@"fi

Save as ~/.local/bin/modus-launch, make executable, run GTK3 apps as modus-launch gedit.

Team

• SANKALP
• tr1x_em

Special Thanks

• darsh: for creating Fabric, which made everything possible.
• gummy bear album: for sharing fantastic code snippets that saved me time and effort.
• axenide: for the amazing config that not only inspired parts of mine but also provided some gems I couldn't resist borrowing.
• E3nviction: for code snippets and ideas that were incredibly helpful.