Matshell is a GPU-accelerated Material Design inspired desktop shell built with AGS/Astal for Hyprland and River. This project draws heavy inspiration from fufexan's AGSv1 config, with design influences from saimoomedits, tailored for both multi-monitor desktop setups and laptops.
This setup tries to achieve sleek, "MacOS-esque" looks with a little bit of rice sprinkled on top.
Now using AGSv3.
- Adaptive Layout: Automatically adapts to desktop or laptop environments by conditionally rendering notebook-specific widgets
- Dynamic Material Design Theming: Change themes on-the-fly via matugen templates
- Multi-monitor Support: Designed with multi-monitor setups in mind
- Hyprland & River Support: Automatic compositor detection
- Cava Visualizer Library: Ships with an extensive lib of optional Cava visualizers to enjoy your music to
- Multimodal Fuzzy & Frecency Picker: Apps, clipboard, wallpapers - all ranked by frequency + recency, loosely based on gnofi.
- Nix Support: Support for NixOS / Home-Manager with dedicated module
- Configurable: Includes option menu to hot-reload styles and components
Show detailed components list
-
📌 Status Bar - Sleek, informative main bar with system information
- Workspace Management - Themed Hyprland or River workspace integration
- System Tray
- Visual Performance Monitoring - CPU & memory
- Simple Clock
-
🎧 Music Player - Media controls, music cover themed
- Audio Visualization - Extensive library of CAVA visualizer styles to choose from
-
🔧 System Menu - Minimalistic core system integration
- Network Management - WiFi scanning, connection management, and status monitoring
- Bluetooth Support - Device pairing, management, and status indicators
- Brightness Controls
- Audio Controls
- Battery Metrics
- Power Profiles
- Notification Center - Intuitive notification management system & DND mode
-
💤 Logout Menu - wlogout-like but ags
-
🎯 Multimodal Launcher - Fast fuzzy search application access and frecency default items
-
💻 On-Screen Display - Tracks Audio, Brightness, and Bluetooth connections
Show dependency list
- aylurs-gtk-shell-git
- libastal-hyprland-git or libastal-river-git
- libastal-tray-git
- libastal-notifd-git
- libastal-apps-git
- libastal-wireplumber-git
- libastal-mpris-git
- libastal-network-git
- libastal-bluetooth-git
- libastal-cava-git
- libastal-battery-git
- libastal-powerprofiles-git
- libgtop
- libadwaita
- libsoup3
- glib-networking
- hyprland or river
- wl-clipboard
- cliphist
- coreutils
- dart-sass
- imagemagick
- networkmanager
- wireplumber
- bluez & bluez-utils (will also run fine without, but throws some non-critical errors on startup)
- adwaita-icon-theme
- ttf-material-symbols-variable-git
- ttf-firacode-nerd
- For matugen theming:
- matugen
- swww or hyprpaper
- image-hct (optional; for proper chroma/tone based theming. Uses imagemagick as fallback)
- upower
- brightnessctl
Note
If you're using an old version of matshell and want to update or you're using your own setup, you will need to move your old config out of ~/.config/ags/ or delete the folder before running the script, as I am not overwriting existing configs. If the Arch install below is broken please open an issue as I don't run Arch and only test this in a VM from time to time.
Run the installation script (Currently supports Arch-based with yay only):
bash <(curl -s https://raw.githubusercontent.com/Neurarian/matshell/refs/heads/master/scripts/install.sh)... and implement the colors into your hyprland config to your liking.
Tip
Use Hyprland layerrules to add some blur to the shell for smoother visuals.
layerrule=blur, bar
layerrule=blur, gtk4-layer-shell
layerrule=ignorealpha 0.2, bar
layerrule=ignorealpha 0.2, gtk4-layer-shell
Note
After a first launch, edit the autogenerated config.json in ~/.config/ags/ to add the shell commands for your terminal, file-manager, browser, resource monitor, and audio control apps to the shell. Defaults are Wezterm, Nautilus, Zen, Resources, and pwvucontrol.
You can also add more advanced bluetooth and wifi apps to the config.json. Their toggles can also be disabled if the matshell controls alone are sufficient for you. Defaults are overskride and gnome-control-center.
Add your wallpaper directory to the config.json to pick wallpapers either randomly via matshell wall-rand or from the wp picker.
Manual install
...Or do it manually by installing the dependencies above and cloning this repo.
❗Make sure to create a backup of your current config if you want to keep it❗
git clone --depth 1 "https://github.com/Neurarian/matshell" "$XDG_CONFIG_HOME/ags/"Finally, add this to your matugen config:
[templates.gtk3]
input_path = "~/.config/ags/matugen/templates/gtk.css"
output_path = "~/.config/gtk-3.0/gtk.css"
[templates.gtk4]
input_path = "~/.config/ags/matugen/templates/gtk.css"
output_path = "~/.config/gtk-4.0/gtk.css"
[templates.ags]
input_path = "~/.config/ags/matugen/templates/ags.scss"
output_path = "~/.config/ags/style/abstracts/_variables.scss"
[templates.hypr]
input_path = "~/.config/ags/matugen/templates/hyprland_colors.conf"
output_path = "~/.config/hypr/hyprland_colors.conf"
[templates.hyprlock]
input_path = "~/.config/ags/matugen/templates/hyprlock_colors.conf"
output_path = "~/.config/hypr/hyprlock_colors.conf"You can generally test out matshell via the flake exposed package nix run github:Neurarian/matshell (nix run github:Neurarian/matshell#matshell-river for the River version). To integrate matshell into your home-manager config you can enable dedicated options from the module:
# ...
imports = [
inputs.matshell.homeManagerModules.default
];
programs.matshell= {
# Enable the basic shell
enable = true;
# Enable a systemd service for matshell
autostart = true;
# Compositor you are using. Defaults to hyprland.
compositor = "hyprland";
# This sets up the entire matugen config & templates.
# If you already have matugen set up you may want to omit this.
# To use the hyprland/hyprlock templates, you would still need to
# import the generated files and add the color aliases to your config as desired.
matugenConfig = true;
};
#...Note
As I don't want to overwrite changes people potentially apply to the stylesheets in ~/.config/ags/ or even their current configs, I do not replace config files already present at ~/.config/ags/ on rebuild. This means, If a new version of matshell changed something style related, you may need to delete the old ~/.config/ags/ folder manually and rebuild again for the stylesheets to be up-to-date.
This project wouldn't be possible without:
- Aylur for the powerful widget toolkit and the gnofi picker
- fufexan's dotfiles for the initial inspiration and foundation
- matugen for the amazing Material Color theming utility
- kotontrion for the GTK4 CAVA Catmull-Rom spline widget
- ARKye03 for the GTK4 circular progress widget which is currently still on its way to be merged into Astal
- saimoomedits' eww-widgets for design influence
- end-4's dots-hyprland for some inspiration on the color generation
matshell.mp4
Floating mode
Full bar mode & cava in bar
Square bar with rounded screen corners & Hyprland blur
