/omarchy

name: omarchy
description: >
  REQUIRED for end-user customization of Linux desktop, window manager, or system config.
  Use when editing ~/.config/hypr/, ~/.config/omarchy/,
  ~/.config/alacritty/, ~/.config/foot/, ~/.config/kitty/, or ~/.config/ghostty/.
  Triggers: Hyprland, window rules, animations, keybindings, monitors, gaps, borders,
  blur, opacity, omarchy-shell, bar, terminal config, themes, background,
  night light, idle, lock screen, screenshots, reminders, layer rules, workspace
  settings, display config, and user-facing omarchy commands. Excludes Omarchy
  source development through `omarchy dev link` workflows.

Omarchy Skill

Manage [Omarchy](https://omarchy.org/) Linux systems - a beautiful, fun, agentic Arch Linux distribution with Hyprland.

This skill is for end-user customization on installed systems. It is not for contributing to Omarchy 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 `~/.config/omarchy/shell.json` (status bar layout, widgets)
• Editing terminal configs (alacritty, foot, kitty, ghostty)
• Editing ANY file in `~/.config/omarchy/`
• Window behavior, animations, opacity, blur, gaps, borders
• Layer rules, workspace settings, display/monitor configuration
• Themes, backgrounds, fonts, appearance changes
• User-facing `omarchy` commands (`omarchy theme ...`, `omarchy refresh ...`, `omarchy 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 Omarchy development tasks** (editing the Omarchy source tree, creating migrations, or running `omarchy dev ...` workflows).

Topic Guides

Deeper instructions for common areas live next to this file. Read the matching guide before starting:

• [`hyprland.md`](hyprland.md) - keybindings, monitors, window rules, and other Hyprland config
• [`plugins.md`](plugins.md) - the Omarchy shell: bar layout, widgets, plugins, idle behavior
• [`theming.md`](theming.md) - themes, backgrounds, and fonts
• [`hooks.md`](hooks.md) - automation hooks that run on system events
• [`capture.md`](capture.md) - screenshots, screen recordings, OCR text capture, and file sharing
• [`contributing.md`](contributing.md) - reporting Omarchy bugs and submitting fixes upstream

Critical Safety Rules

For privileged commands, follow the Privilege Escalation rules below: `sudo` when a terminal is available for the password prompt, `pkexec` when it is not. Do not wrap commands that already manage privilege elevation themselves.

**For end-user customization tasks, NEVER modify anything in `/usr/share/omarchy/`** - but READING is safe and encouraged.

This directory is owned by the omarchy package. Any local changes will be overwritten on the next `omarchy update`.

/usr/share/omarchy/     # READ-ONLY - NEVER EDIT (reading is OK)
├── bin/                    # Command source (packaged binaries are on PATH)
├── config/                 # Default config templates
├── themes/                 # Stock themes
├── default/                # System defaults
├── shell/                  # Omarchy shell source and defaults
├── migrations/             # Update migrations
└── install/                # Installation scripts

**Reading `/usr/share/omarchy/` is SAFE and useful** - do it freely to:

• Understand how omarchy commands work: `omarchy theme set --help` or `cat $(which omarchy-theme-set)`
• See default configs before customizing: `cat "$OMARCHY_PATH/config/omarchy/shell.json"`
• Check stock theme files to copy for customization
• Reference default hyprland settings: `cat /usr/share/omarchy/default/hypr/*`

**Always use these safe locations instead:**

• `~/.config/` - User configuration (safe to edit)
• `~/.config/omarchy/themes/<custom-name>/` - Custom themes
• `~/.config/omarchy/hooks/` - Custom automation hooks

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

Privilege Escalation

For an interactive script or command run in a visible terminal, use `sudo` for privileged work. Omarchy may grant passwordless `sudo` access to particular commands, and the terminal is the appropriate place to request a password when one is needed.

Use `pkexec` only when the caller cannot interact with a terminal or cannot enter a password there, such as a command launched by an agent or a graphical background process. Do not replace `sudo` with `pkexec` merely because a command changes system state.

System Architecture

Omarchy is built on:

| Component | Purpose | Config Location | |-----------|---------|-----------------| | **Arch Linux** | Base OS | `/etc/`, `~/.config/` | | **Hyprland** | Wayland compositor/WM | `~/.config/hypr/` | | **Omarchy shell** | Status bar + notifications (Quickshell) | `~/.config/omarchy/shell.json` | | **Launcher/menus** | Quickshell menu | `~/.config/omarchy/extensions/omarchy-menu.jsonc` | | **Alacritty/Foot/Kitty/Ghostty** | Terminals | `~/.config/<terminal>/` | | **Omarchy OSD** | On-screen display | Quickshell plugin |

Command Discovery

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

# List every documented command and its summary (--all includes hidden commands)
omarchy commands

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

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

# Machine-readable listing (binary, route, summary, args, aliases)
omarchy