Quick Start Guide

Quick Start Guide

Get Matshell up and running in minutes.

First Launch

After installation, launch Matshell either via:

ags run

or bundle it before, e.g., via:

cd $HOME/.config/ags/
ags bundle app.ts matshell
sudo mv ./matshell /usr/local/bin/
matshell

Initial Configuration

1. Edit config.json

On first launch, Matshell generates ~/.config/ags/config.json. Edit this file to configure your preferred applications:

Key Settings:

• app.terminal: Your preferred terminal emulator

• app.file-manager: Default file manager

• app.resource-monitor: Process / resource monitor

• app.browser: Web browser

• wallpaper.dir: Directory containing your wallpapers for the picker

{
  "app.browser": "zen",
  "app.file-manager": "nautilus",
  "app.resource-monitor": "resources", 
  "app.terminal": "wezterm",
  "app.wifi": "XDG_CURRENT_DESKTOP=GNOME gnome-control-center wifi",
  "app.audio": "pwvucontrol",
  "wallpaper.dir": "~/Pictures/Wallpapers"
}

2. Set Up Wallpaper & Theme

Matshell uses matugen for dynamic theming based on your wallpaper.

Random Wallpaper:

ags request wall-rand --instance 'matshell'

Choose from Picker:

Open the wallpaper picker from the bottom of the sidebar menu in Matshell (OS-Icon). You can either search for one of your wallpapers and let matshell automatically decide on the matugen scheme and mode, or you can manually set them from the drop-down menus.

3. Configure Compositor Integration

Hyprland

Add these layer rules to your Hyprland configuration for optimal visuals:

layerrule = blur, bar
layerrule = blur, gtk4-layer-shell
layerrule = ignorealpha 0.2, bar
layerrule = ignorealpha 0.2, gtk4-layer-shell

Import the generated color scheme into your main hyprland config:

source = ~/.config/hypr/hyprland_colors.conf

and use the colors, e.g., for the window borders.

River

River theming support going to be automatic but currently not yet included. Ensure libastal-river-git is installed instead of libastal-hyprland-git.

Essential Keybindings

While Matshell doesn't define keybindings (these are set in your compositor), here are my personal bindings:

# Picker

bind=SUPER, A, exec, ags request picker --instance 'matshell'

# Logout Menu
bind=SUPER SHIFT, Q, exec, ags request logout --instance 'matshell'

# Sidebar
bind=SUPER, N, exec, ags request sidebar --instance 'matshell'

# Random Wallpaper
bind=SUPER SHIFT, W, exec, ags request wall-rand --instance 'matshell'

Add these to your compositor configuration to control Matshell widgets and functions.

Testing the Shell

Status Bar

The main status bar should appear at the top of your screen, displaying:

• Workspace & Client indicators

• Current song, if anything is playing

• System tray

• CPU/Memory usage

• System information if available (network, battery, Bluetooth)

• Clock

Picker

Open the picker to test application searching. It starts empty, but uses frecency-based ranking (frequency + recency) to prioritize your commonly-used apps. Search any app and launch it to populate the frecency defaults. The same principle holds true for all other search modes of the picker.

System Menu

Access the system menu to verify:

• Network management (Wifi connection management)

• Bluetooth connectivity and device management

• Notification center

• Power-profile management and battery level on battery powered devices

• Audio controls

• Brightness control if supported

Sidebar

The sidebar contains several "mini-widgets".

• A more detailed clock & date

• Current weather data todays forecast

• Hardware monitoring

• Matshell settings

• Quick-launch dock

Customization Options

Matshell includes an in-shell settings menu accessible from the sidebar. Here you can:

• Toggle bar style (floating/full/rounded corners)

• Toggle and choose the OS-Icon

• Toggle and choose CAVA visualizer styles in the bar and the music player

• Toggle specific opt-out components

For more details visit the configuration guide //TODO

Troubleshooting

If you encounter issues during first launch, check:

• All dependencies are installed

• A compatible compositor is running

If the issues persist feel free to write an Issue.