Installation

Installation guide

This guide covers installing Matshell.

Prerequisites

Before installing Matshell, ensure your using a supported Wayland compositor (Hyprland or River)

Supported Distributions

Arch Linux

Automated Installation

The easiest way to install Matshell on Arch-based distributions is via the installation script:

bash <(curl -s https://raw.githubusercontent.com/Neurarian/matshell/refs/heads/master/scripts/install.sh)

This script will:

• Install all required dependencies via yay
• Clone the Matshell repository to ~/.config/ags/
• Configure matugen templates

Note

Important: If you have an existing AGS configuration, back it up before running the installation script. The installer will not overwrite existing configs at ~/.config/ags/.

Manual Installation

Show manual installation steps

1. Install Dependencies

Using yay or your preferred AUR helper:

yay -S aylurs-gtk-shell-git \
libastal-hyprland-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 \
wl-clipboard \
cliphist \
dart-sass \
imagemagick \
networkmanager \
wireplumber \
bluez bluez-utils \
adwaita-icon-theme \
ttf-material-symbols-variable-git \
ttf-firacode-nerd \
matugen \
swww

For River users, replace libastal-hyprland-git with libastal-river-git and hyprland with river.

2. Clone Repository

git clone --depth 1 "https://github.com/Neurarian/matshell" "$XDG_CONFIG_HOME/ags/"

3. Configure Matugen

Add the following to your matugen config (~/.config/matugen/config.toml):

[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"

NixOS

See the dedicated NixOS Integration page for detailed instructions.

Quick start:

{
  inputs.matshell.url = "github:Neurarian/matshell";
  
  # In your home-manager configuration:
  imports = [ inputs.matshell.homeManagerModules.default ];
  
  programs.matshell = {
    enable = true;
    autostart = true;
    compositor = "hyprland"; # or "river"
    matugenConfig = true;
  };
}

Dependency Reference

Required Dependencies

Core dependencies required for Matshell to function:

Package	Purpose
aylurs-gtk-shell-git	AGS framework
libastal-*-git	Astal library modules
libgtop	System monitoring
libsoup & glib-networking	Weather API fetching
libadwaita	Adw.Clamp & Adw.Spinner access
matugen	Material Design theming
dart-sass	Style-sheet compilation
imagemagick	Image manipulation
networkmanager	Network management
wireplumber	Audio management
wl-clipboard	Clipboard support
cliphist	Clipboard history
ttf-* & adwaita-icon-theme	Used fonts & icons
swww or hyprpaper	Wallpaper utilities

Optional Dependencies

Enhanced functionality:

Package	Purpose
upower	Battery management (laptops)
brightnessctl	Brightness control (laptops)
image-hct	Advanced automatic scheme & mode setting
bluez	Bluetooth support

Post-Installation

Proceed to the Quick Start Guide to configure Matshell for your system.