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 playerctl matugen-bin 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

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

See Configuration Guide for full reference.

Documentation

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
FAQs & Tips	Troubleshooting, shortcuts, live reload

Custom Mods

Define panel buttons in config/mods.toml:

[Mods.terminal]
icon = "terminal.svg"
icon-size = 16
order = 1
on-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.