Modus/README.md

Home Screen:

Lock Screen:

Quick Start

git clone https://github.com/S4NKALP/Modus ~/.config/Modus
cd ~/.config/Modus
./install.sh

Tip

Post Installation

• Install recommended Icon theme , GTK theme and Cursor Theme
  
• Check config/hypr/modus.lua edit it according to your device and copy it to your hyprland config
• For Lock Screen Bind keys to uv run lock

Manual Installation

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 apple-fonts webp-pixbuf-loader cinnamon-desktop libmediaart acpi brightnessctl power-profiles-daemon ddcutil 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
git clone https://github.com/S4NKALP/Modus ~/.config/Modus
cd ~/.config/Modus
uv sync

# Compile App Switcher C-backend
cd src/window/switcher/app-capture
meson setup builddir
meson compile -C builddir
cd ../../../..

# Compile 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
cd ../../..

uv run start

Global Menu Compatibility

MODUS injects the GTK3 menu-button shim (libmenu_button_shim.so) only into GTK3 apps, and only when launched through MODUS (dock, spotlight, panel). GTK4 apps are never touched, so they launch normally — a global LD_PRELOAD of this shim would otherwise crash every GTK4 process.

Terminal-launched GTK3 apps

Apps you start directly from a terminal don't go through MODUS, so they don't get the shim. They still work fine; they just miss the synthetic button-release fix the shim provides. To get it back without a dangerous system-wide LD_PRELOAD, use a thin wrapper that detects GTK3 and injects the shim only for that process:

#!/usr/bin/env bash
# ~/.local/bin/modus-launch — GTK3-aware launcher for the global menu shim
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

Make it executable (chmod +x ~/.local/bin/modus-launch) and run GTK3 apps as modus-launch gedit from the terminal. GTK4 apps fall through to a normal launch.

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, examples
FAQs & Tips	Troubleshooting, shortcuts, live reload
Contributing	Setup, code style, commit conventions

Configuration

Config files in config/, using TOML format:

File	Purpose
config.toml	Main settings (switcher, wallpaper, notifications)
mods.toml	Custom panel buttons
dock.toml	Pinned dock apps

See Configuration Guide for full reference.

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)
• Full shell syntax (&&, |) via sh -c
• Live reload — edit and changes apply instantly

Spotlight Plugins

The spotlight search (Super+D) is powered by plugins. Drop a .py file in config/plugins/ and it works instantly.

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

Plugin development:

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

See Spotlight Plugins for full docs and examples.

Team

• SANKALP
• tr1x_em

Special Thanks

A big thank you to the following people for their incredible help with code and creative ideas. Your help made a real difference!

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

I truly appreciate your support