basecamp/omarchy

Overview

This skill manages Omarchy desktop and related configuration on Linux systems. It is required for any changes to Hyprland, Waybar, Walker, terminals, themes, or files under ~/.config/ that Omarchy controls. It enforces safe patterns, provides commands to apply or revert changes, and prevents destructive edits to the distribution-managed source tree.

How this skill works

The skill inspects and edits user configuration files in ~/.config/ (Hyprland, Waybar, Walker, Alacritty, Kitty, Ghostty, Mako, Omarchy themes/hooks) and discovers available omarchy-* commands. It recommends safe edit workflows, runs restarts or reloads where required, and points to the correct omarchy helpers (restart, refresh, theme-set, debug). It forbids modifying ~/.local/share/omarchy/ and guides reading defaults from that read-only location.

When to use it

• Before editing any file in ~/.config/hypr/, ~/.config/waybar/, ~/.config/walker/, ~/.config/mako/, ~/.config/omarchy/, or terminal configs
• When adding or changing keybindings, window rules, animations, gaps, borders, blur, opacity, or workspace behavior
• When changing displays/monitors, wallpapers, themes, fonts, night light, or lock screen settings
• When running any omarchy-* command (install, restart, refresh, theme, update, debug, etc.)
• When creating custom themes or hooks under ~/.config/omarchy/
• When troubleshooting desktop behavior or preparing to reset configs to defaults

Best practices

• Always edit files in ~/.config/ (user config), never write to ~/.local/share/omarchy/ (read-only source files)
• Backup the file before changes (e.g., cp file file.bak.$(date +%s)) and use omarchy-refresh-* to revert safely
• Check current keybindings with omarchy-menu-keybindings --print and unbind any existing binding before reassigning
• Use hyprctl reload for Hyprland changes and omarchy-restart-waybar / omarchy-restart-walker / omarchy-restart-terminal where auto-reload is not supported
• Fetch current Hyprland window-rules syntax from the official Hyprland wiki before writing rules
• Run omarchy-debug --no-sudo --print when collecting diagnostics to avoid interactive sudo prompts

Example use cases

• Add a custom SUPER+E keybinding: inspect current binding, add an unbind if needed, then append bind to ~/.config/hypr/bindings.conf
• Apply a new theme: create ~/.config/omarchy/themes/mytheme, add assets, then run omarchy-theme-set "MyTheme"
• Fix a monitor layout: edit ~/.config/hypr/monitors.conf and verify with hyprctl monitors
• Reset Waybar after a bad edit: run omarchy-refresh-waybar (creates backup, copies defaults, restarts bar)
• Automate actions on theme change: create an executable hook in ~/.config/omarchy/hooks/theme-set