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 = 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.