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

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

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:

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