omarchy

name	omarchy
description	Manage and configure Omarchy Linux systems. Use when user asks about Omarchy, Hyprland, themes, keybindings, system config, or any omarchy-* commands.

Omarchy Skill

Manage Omarchy Linux systems using natural language.

⛔ NEVER MODIFY CORE FILES

DO NOT edit, write, or delete any files in ~/.local/share/omarchy/

This directory contains Omarchy's core system files. User configuration belongs in ~/.config/ instead.

If you need to change behavior controlled by a file in ~/.local/share/omarchy/, find or create the corresponding override in ~/.config/.

Discovery

Omarchy provides ~145 commands following the pattern omarchy-<category>-<action>.

Find Commands

# List all omarchy commands
compgen -c | grep -E '^omarchy-' | sort -u

# Find commands by category
compgen -c | grep -E '^omarchy-theme'
compgen -c | grep -E '^omarchy-restart'

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

Command Categories

Prefix	Purpose	Example
omarchy-refresh-*	Reset config to Omarchy defaults (backs up first)	omarchy-refresh-waybar
omarchy-restart-*	Restart a service/app	omarchy-restart-waybar
omarchy-toggle-*	Toggle feature on/off	omarchy-toggle-nightlight
omarchy-theme-*	Theme management	omarchy-theme-set <name>
omarchy-install-*	Install optional software	omarchy-install-docker-dbs
omarchy-launch-*	Launch apps	omarchy-launch-browser
omarchy-cmd-*	System commands	omarchy-cmd-screenshot
omarchy-pkg-*	Package management	omarchy-pkg-install <pkg>
omarchy-setup-*	Initial setup tasks	omarchy-setup-fingerprint
omarchy-update-*	System updates	omarchy-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

Restart/Refresh:

• omarchy-refresh-hyprland - Reset to defaults
• Hyprland auto-reloads on config save (no restart needed)
• omarchy-restart-hypridle / omarchy-restart-hyprsunset for those services

Waybar (Status Bar)

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

Restart/Refresh:

• omarchy-restart-waybar - Restart waybar
• omarchy-refresh-waybar - Reset to defaults
• omarchy-toggle-waybar - Show/hide

Walker (App Launcher)

~/.config/walker/
└── config.toml        # Launcher configuration

Restart/Refresh:

• omarchy-restart-walker
• omarchy-refresh-walker

Terminals

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

Restart:

• omarchy-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

Omarchy Data

~/.local/share/omarchy/
├── bin/               # All omarchy-* scripts
├── config/            # Default config templates
├── themes/            # Installed themes
└── version            # Current version info

Safe Editing Pattern

When modifying any Omarchy config:

1. Read Current Config

cat ~/.config/<app>/config

2. Backup Before Changes

cp ~/.config/<app>/config ~/.config/<app>/config.bak.$(date +%s)

3. Make Changes

Use the Edit tool. Preserve existing structure and comments.

4. Apply Changes

# For most apps, use the restart command
omarchy-restart-<app>

# Or reset to defaults (creates backup automatically)
omarchy-refresh-<app>

5. Explain What You Did

After completing changes, include a Learn More section to help the user understand what happened:

> **Learn More**
>
> [Explain what file(s) were modified or commands were run]
> [Explain why these changes achieve the user's goal]
> [Explain key config options that were set and what they control]

Example:

Learn More

Modified ~/.config/hypr/looknfeel.conf to change window gaps. The gaps_in setting controls space between adjacent windows (set to 5px). The gaps_out setting controls space between windows and screen edges (set to 10px).

Common Tasks

Themes

omarchy-theme-list              # Show available themes
omarchy-theme-current           # Show current theme
omarchy-theme-set <name>        # Apply theme
omarchy-theme-next              # Cycle to next theme
omarchy-theme-bg-next           # Cycle wallpaper
omarchy-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: omarchy-menu-keybindings

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

Screenshots

• omarchy-cmd-screenshot - Interactive screenshot
• omarchy-cmd-screenrecord - Toggle screen recording

System

omarchy-update                  # Full system update
omarchy-version                 # Show Omarchy version
omarchy-debug                   # Debug info for troubleshooting
omarchy-lock-screen             # Lock screen
omarchy-cmd-shutdown            # Shutdown
omarchy-cmd-reboot              # Reboot

Fonts

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

Troubleshooting

# Check Omarchy state
omarchy-state

# Debug information
omarchy-debug

# Upload logs for support
omarchy-upload-log

# Reset specific config to defaults
omarchy-refresh-<app>

# Full reinstall (nuclear option)
omarchy-reinstall

Omarchy Manual

IMPORTANT: For general "how do I" questions, ALWAYS fetch the relevant manual page BEFORE answering. The manual at https://learn.omacom.io contains Omarchy-specific guidance that may differ from generic Linux advice.

When to Fetch the Manual

Always fetch first when users ask:

• "How do I..." / "What is..." / "Why does..." questions
• Questions about installing/running software (Windows, games, apps)
• Questions about concepts, workflows, or best practices
• Topics where Omarchy may have a specific approach

Manual Index

Match the user's question to topic(s) below and fetch the page(s) before responding:

Topic	Keywords	URL
Welcome / Overview	what is omarchy, introduction, about	/2/the-omarchy-manual/91/welcome-to-omarchy
Getting Started	install, installation, setup, ISO, new user	/2/the-omarchy-manual/50/getting-started
Navigation	tiling, workspaces, move, resize, focus, window management	/2/the-omarchy-manual/51/navigation
Themes	theme, appearance, colors, look, style	/2/the-omarchy-manual/52/themes
Extra Themes	community themes, more themes, additional themes	/2/the-omarchy-manual/90/extra-themes
Making Themes	create theme, custom theme, theme development	/2/the-omarchy-manual/92/making-your-own-theme
Hotkeys	keybindings, shortcuts, keyboard, hotkey reference	/2/the-omarchy-manual/53/hotkeys
PDFs	pdf, forms, documents, xournal	/2/the-omarchy-manual/54/filling-out-pdfs
Applications	apps, software, included, default apps	/2/the-omarchy-manual/55/the-applications
Neovim	neovim, nvim, vim, editor	/2/the-omarchy-manual/56/neovim
Shell Tools	fzf, zoxide, ripgrep, rg, search	/2/the-omarchy-manual/57/shell-tools
Shell Functions	compress, format, convert, shell utilities	/2/the-omarchy-manual/58/shell-functions
TUIs	lazygit, lazydocker, btop, terminal ui	/2/the-omarchy-manual/59/tuis
GUIs	obsidian, pinta, localsend, graphical apps	/2/the-omarchy-manual/60/guis
Commercial GUIs	1password, typora, paid apps	/2/the-omarchy-manual/61/commercial-guis
Development Tools	dev, programming, coding, ide	/2/the-omarchy-manual/62/development-tools
Web Apps	web app, pwa, browser apps	/2/the-omarchy-manual/63/web-apps
Configuration	config, customize, settings	/2/the-omarchy-manual/64/configuration
Dotfiles	dotfiles, .config, config files	/2/the-omarchy-manual/65/dotfiles
Other Packages	pacman, yay, aur, arch packages	/2/the-omarchy-manual/66/other-packages
FAQ	faq, questions, common issues	/2/the-omarchy-manual/67/faq
Updates	update, upgrade, system update	/2/the-omarchy-manual/68/updates
Gaming	games, steam, retroarch, gaming	/2/the-omarchy-manual/71/gaming
Troubleshooting	problem, issue, fix, broken, not working	/2/the-omarchy-manual/88/troubleshooting
Backgrounds	wallpaper, background, custom wallpaper	/2/the-omarchy-manual/89/backgrounds
Security	encryption, firewall, security, luks	/2/the-omarchy-manual/93/security
Fonts	font, typeface, typography	/2/the-omarchy-manual/94/fonts
Prompt	starship, prompt, terminal prompt	/2/the-omarchy-manual/95/prompt
Manual Installation	manual install, arch install, step by step	/2/the-omarchy-manual/96/manual-installation
Mac Support	mac, macbook, intel mac, apple	/2/the-omarchy-manual/97/mac-support
Windows VM	windows, run windows, install windows, vm, virtual machine, microsoft	/2/the-omarchy-manual/100/windows-vm
System Snapshots	snapshot, backup, restore, timeshift	/2/the-omarchy-manual/101/system-snapshots
Common Tweaks	tweak, customize, adjust, modify	/2/the-omarchy-manual/102/common-tweaks
Input Devices	keyboard, mouse, trackpad, touchpad, input	/2/the-omarchy-manual/78/keyboard-mouse-trackpad
Fingerprint / Fido2	fingerprint, fido, yubikey, biometric	/2/the-omarchy-manual/77/fingerprint-fido2-authentication
Monitors	monitor, display, screen, resolution, scaling	/2/the-omarchy-manual/86/monitors
Running Omarchy	vm, virtualbox, vmware, platforms	/2/the-omarchy-manual/79/omarchy-on

Fetching Manual Pages

When a user asks a general question:

1. Identify relevant topic(s) from the index above
2. Fetch the page using WebFetch with the full URL:

   https://learn.omacom.io<path>
   

3. Extract the answer from the page content
4. Summarize the relevant information for the user

Examples:

• "How do I set up my fingerprint reader?" → Fetch /2/the-omarchy-manual/77/fingerprint-fido2-authentication
• "How do I install Windows on Omarchy?" → Fetch /2/the-omarchy-manual/100/windows-vm
• "How do I install Steam?" → Fetch /2/the-omarchy-manual/71/gaming

Example Requests

• "Change my theme to catppuccin"
• "Add a keybinding for Super+E to open file manager"
• "Configure my external monitor"
• "Make the window gaps smaller"
• "Set up night light to turn on at sunset"
• "Show me what omarchy commands are available for bluetooth"
• "Increase waybar height"
• "Change my terminal font"
• "How do I install Steam?"
• "How do I install Windows on Omarchy?"
• "What keyboard shortcuts are available?"
• "How do I set up my fingerprint reader?"