solace

name

solace

description

REQUIRED for end-user customization of Linux desktop, window manager, or system config. Use when editing ~/.config/hypr/, ~/.config/waybar/, ~/.config/walker/, ~/.config/alacritty/, ~/.config/foot/, ~/.config/kitty/, ~/.config/ghostty/, ~/.config/mako/, or ~/.config/solace/. Triggers: Hyprland, window rules, animations, keybindings, monitors, gaps, borders, blur, opacity, waybar, walker, terminal config, themes, wallpaper, night light, idle, lock screen, screenshots, reminders, layer rules, workspace settings, display config, and user-facing solace commands. Excludes Solace source development in ~/.local/share/solace/ and `solace dev` workflows.

Solace Skill

Manage Solace Linux systems - a beautiful, modern, opinionated Arch Linux distribution with Hyprland.

This skill is for end-user customization on installed systems. It is not for contributing to Solace source code.

When This Skill MUST Be Used

ALWAYS invoke this skill for end-user requests involving ANY of these:

• Editing ANY file in ~/.config/hypr/ (window rules, animations, keybindings, monitors, etc.)
• Editing ANY file in ~/.config/waybar/, ~/.config/walker/, ~/.config/mako/
• Editing terminal configs (alacritty, foot, kitty, ghostty)
• Editing ANY file in ~/.config/solace/
• Window behavior, animations, opacity, blur, gaps, borders
• Layer rules, workspace settings, display/monitor configuration
• Themes, wallpapers, fonts, appearance changes
• User-facing solace commands (solace theme ..., solace refresh ..., solace restart ..., etc.)
• Screenshots, screen recording, reminders, night light, idle behavior, lock screen

If you're about to edit a config file in ~/.config/ on this system, STOP and use this skill first.

Do NOT use this skill for Solace development tasks (editing files in ~/.local/share/solace/, creating migrations, or running solace dev ... workflows).

Critical Safety Rules

For end-user customization tasks, NEVER modify anything in ~/.local/share/solace/ - but READING is safe and encouraged.

This directory contains Solace's source files managed by git. Any changes will be:

• Lost on next solace update
• Cause conflicts with upstream
• Break the system's update mechanism

~/.local/share/solace/     # READ-ONLY - NEVER EDIT (reading is OK)
├── bin/                    # Source scripts (symlinked to PATH)
├── config/                 # Default config templates
├── themes/                 # Stock themes
├── default/                # System defaults
├── migrations/             # Update migrations
└── install/                # Installation scripts

Reading ~/.local/share/solace/ is SAFE and useful - do it freely to:

• Understand how solace commands work: solace theme set --help or cat $(which solace-theme-set)
• See default configs before customizing: cat ~/.local/share/solace/config/waybar/config.jsonc
• Check stock theme files to copy for customization
• Reference default hyprland settings: cat ~/.local/share/solace/default/hypr/*

Always use these safe locations instead:

• ~/.config/ - User configuration (safe to edit)
• ~/.config/solace/themes/<custom-name>/ - Custom themes (must be real directories)
• ~/.config/solace/hooks/ - Custom automation hooks

If the request is to develop Solace itself, this skill is out of scope. Follow repository development instructions instead of this skill.

System Architecture

Solace is built on:

Component	Purpose	Config Location
Arch Linux	Base OS	/etc/, ~/.config/
Hyprland	Wayland compositor/WM	~/.config/hypr/
Waybar	Status bar	~/.config/waybar/
Walker	App launcher	~/.config/walker/
Alacritty/Foot/Kitty/Ghostty	Terminals	~/.config/<terminal>/
Mako	Notifications	~/.config/mako/
SwayOSD	On-screen display	~/.config/swayosd/

Command Discovery

Solace ships a single solace CLI that dispatches to all solace-* binaries via solace <group> <action>. Always prefer this form — it is self-documenting and stable. The underlying solace-* binaries still exist on PATH and remain safe to read for source.

# List every documented command and its summary
solace commands

# Show the commands inside a group
solace theme --help
solace refresh --help
solace restart --help

# Show help for a specific command (does not execute it)
solace theme set --help

# Machine-readable listing (binary, route, summary, args, aliases)
solace commands --json

# Read a command's source to understand it
cat $(which solace-theme-set)

Command Groups

Run solace --help for the full list. The most common groups:

Group	Purpose	Example
solace refresh	Reset config to defaults (backs up first)	solace refresh waybar
solace restart	Restart a service/app	solace restart waybar
solace toggle	Toggle feature on/off	solace toggle nightlight
solace theme	Theme management	solace theme set <name>
solace install	Install optional software / packages	solace install docker dbs
solace launch	Launch apps	solace launch browser
solace capture	Screenshots and recordings	solace capture screenshot
solace reminder	Desktop notification reminders	solace reminder 15 "Pickup Jack"
solace pkg	Package management	solace pkg install <pkg>
solace setup	Initial setup tasks	solace setup fingerprint
solace update	System updates	solace update

Configuration Locations

Hyprland (Window Manager)

~/.config/hypr/
├── hyprland.conf      # Main config (sources others)
├── bindings.conf      # Keybindings
├── monitors.conf      # Display configuration
├── input.conf         # Keyboard/mouse settings
├── looknfeel.conf     # Appearance (gaps, borders, animations)
├── envs.conf          # Environment variables
├── autostart.conf     # Startup applications
├── hypridle.conf      # Idle behavior (screen off, lock, suspend)
├── hyprlock.conf      # Lock screen appearance
└── hyprsunset.conf    # Night light / blue light filter

Key behaviors:

• Hyprland auto-reloads on config save (no restart needed for most changes)
• Use hyprctl reload to force reload
• After ANY Hyprland config change, validate with hyprctl reload followed by hyprctl configerrors
• If hyprctl configerrors reports errors, address them and rerun validation until clean or until a real blocker is identified
• Use solace refresh hyprland to reset to defaults

Waybar (Status Bar)

~/.config/waybar/
├── config.jsonc       # Bar layout and modules (JSONC format)
└── style.css          # Styling

Waybar does NOT auto-reload. You MUST run solace restart waybar after any config changes.

Commands: solace restart waybar, solace refresh waybar, solace toggle waybar

Terminals

~/.config/alacritty/alacritty.toml
~/.config/foot/foot.ini
~/.config/kitty/kitty.conf
~/.config/ghostty/config

Command: solace restart terminal

Other Configs

App	Location
btop	~/.config/btop/btop.conf
fastfetch	~/.config/fastfetch/config.jsonc
lazygit	~/.config/lazygit/config.yml
starship	~/.config/starship.toml
git	~/.config/git/config
walker	~/.config/walker/config.toml

Safe Customization Patterns

Pattern 1: Edit User Config Directly

For simple changes, edit files in ~/.config/:

# 1. Read current config
cat ~/.config/hypr/bindings.conf

# 2. Backup before changes
cp ~/.config/hypr/bindings.conf ~/.config/hypr/bindings.conf.bak.$(date +%s)

# 3. Make changes with Edit tool

# 4. Apply changes
# - Hyprland: auto-reloads on save, but MUST validate with `hyprctl reload` and `hyprctl configerrors`
# - Waybar: MUST restart with `solace restart waybar`
# - Walker: MUST restart with `solace restart walker`
# - Terminals: MUST restart with `solace restart terminal`

Pattern 2: Make a new theme

1. Create a directory under ~/.config/solace/themes.
2. See how an existing theme is done via ~/.local/share/solace/themes/catppuccin.
3. Download a matching background (or several) from the internet and put them in ~/.config/solace/themes/[name-of-new-theme]
4. When done with the theme, run solace theme set "Name of new theme"

Pattern 3: Use Hooks for Automation

Create scripts in ~/.config/solace/hooks/ to run automatically on events:

# Available hooks (see samples in ~/.config/solace/hooks/):
~/.config/solace/hooks/
├── theme-set        # Runs after theme change (receives theme name as $1)
├── font-set         # Runs after font change
└── post-update      # Runs after `solace update`

Example hook (~/.config/solace/hooks/theme-set):

#!/bin/bash
THEME_NAME=$1
echo "Theme changed to: $THEME_NAME"
# Add custom actions here

Pattern 4: Reset to Defaults -- ALWAYS SEEK USER CONFIRMATION BEFORE RUNNING

When customizations go wrong:

# Reset specific config (creates backup automatically)
solace refresh waybar
solace refresh hyprland

# The refresh command:
# 1. Backs up current config with timestamp
# 2. Copies default from ~/.local/share/solace/config/
# 3. Restarts the component

Common Tasks

Themes

solace theme list              # Show available themes
solace theme current           # Show current theme
solace theme set <name>        # Apply theme (use "Tokyo Night" not "tokyo-night")
solace theme bg next           # Cycle wallpaper
solace theme install <url>     # Install from git repo

Keybindings

Edit ~/.config/hypr/bindings.conf. Format:

bind = SUPER, Return, exec, xdg-terminal-exec
bind = SUPER, Q, killactive
bind = SUPER SHIFT, E, exit

View current bindings: solace menu keybindings --print

IMPORTANT: When re-binding an existing key:

1. First check existing bindings: solace menu keybindings --print
2. If the key is already bound, you MUST add an unbind directive BEFORE your new bind
3. Inform the user what the key was previously bound to

Example - rebinding SUPER+F (which is bound to fullscreen by default):

# Unbind existing SUPER+F (was: fullscreen)
unbind = SUPER, F
# New binding for file manager
bind = SUPER, F, exec, nautilus

Always tell the user: "Note: SUPER+F was previously bound to fullscreen. I've added an unbind directive to override it."

Display/Monitors

Edit ~/.config/hypr/monitors.conf. Format:

monitor = eDP-1, 1920x1080@60, 0x0, 1
monitor = HDMI-A-1, 2560x1440@144, 1920x0, 1

List monitors: hyprctl monitors

Window Rules

CRITICAL: Hyprland window rules syntax changes frequently between versions.

Before writing ANY window rules, you MUST fetch the current documentation from the official Hyprland wiki:

• https://github.com/hyprwm/hyprland-wiki/blob/main/content/Configuring/Window-Rules.md

DO NOT rely on cached or memorized window rule syntax. The format has changed multiple times and using outdated syntax will cause errors or unexpected behavior.

Window rules go in ~/.config/hypr/hyprland.conf or a sourced file. Always verify the current syntax from the wiki first.

Fonts

solace font list               # Available fonts
solace font current            # Current font
solace font set <name>         # Change font

System

solace update                  # Full system update
solace version                 # Show Solace version
solace debug --no-sudo --print # Debug info (ALWAYS use these flags)
solace system lock             # Lock screen
solace system shutdown         # Shutdown
solace system reboot           # Reboot

IMPORTANT: Always run solace debug with --no-sudo --print flags to avoid interactive sudo prompts that will hang the terminal.

Troubleshooting

# Get debug information (ALWAYS use these flags to avoid interactive prompts)
solace debug --no-sudo --print

# Upload logs for support
solace upload log

# Reset specific config to defaults
solace refresh <app>

# Refresh specific config file
# config-file path is relative to ~/.config/
# eg. `solace refresh config hypr/hyprlock.conf` will refresh ~/.config/hypr/hyprlock.conf
solace refresh config <config-file>

# Full reinstall of configs (nuclear option)
solace reinstall

Decision Framework

When user requests system changes:

1. Is it a stock solace command? Use it directly
2. Is it a config edit? Edit in ~/.config/, never ~/.local/share/solace/
3. Is it a theme customization? Create a NEW custom theme directory
4. Is it automation? Use hooks in ~/.config/solace/hooks/
5. Is it a package install? Use solace pkg add <pkgs...> (or solace pkg aur add <pkgs...> for AUR-only packages)
6. Unsure if command exists? Run solace commands (or solace <group> --help for one group)

Reminder Requests

When the user asks to set a reminder, use solace reminder <minutes> [message] directly. Convert natural language durations to minutes and title-case short reminder labels when appropriate.

solace reminder 15 "Pickup Jack"
solace reminder 60 "Check laundry"
solace reminder show
solace reminder clear

Out of Scope

This skill intentionally does not cover Solace source development. Do not use this skill for:

• Editing files in ~/.local/share/solace/ (bin/, config/, default/, themes/, migrations/, etc.)
• Creating or editing migrations
• Running solace dev ... commands

Example Requests

• "Change my theme to catppuccin" -> solace theme set catppuccin
• "Add a keybinding for Super+E to open file manager" -> Check existing bindings first, add unbind if needed, then add bind in ~/.config/hypr/bindings.conf
• "Configure my external monitor" -> Edit ~/.config/hypr/monitors.conf
• "Make the window gaps smaller" -> Edit ~/.config/hypr/looknfeel.conf
• "Set up night light to turn on at sunset" -> solace toggle nightlight or edit ~/.config/hypr/hyprsunset.conf
• "Set a reminder to pickup jack in 15 minutes" -> solace reminder 15 "Pickup Jack"
• "Show my reminders" -> solace reminder show
• "Clear all reminders" -> solace reminder clear
• "Customize the catppuccin theme colors" -> Create ~/.config/solace/themes/catppuccin-custom/ by copying from stock, then edit
• "Run a script every time I change themes" -> Create ~/.config/solace/hooks/theme-set
• "Reset waybar to defaults" -> solace refresh waybar