/omarchy

name: omarchy
description: >
  REQUIRED for end-user customization of Linux desktop, window manager, or system config.
  Use when editing ANY file in ~/.config/, ~/.config/hypr/, ~/.config/omarchy/,
  ~/.config/alacritty/, ~/.config/foot/, ~/.config/kitty/, or ~/.config/ghostty/.
  Triggers: Hyprland, window rules, window behavior, animations, keybindings, monitors, gaps, borders,
  blur, opacity, omarchy-shell, bar, widgets, terminal config, themes, fonts, background,
  night light, idle, lock screen, screenshots, screen recording, reminders, layer rules, workspace
  settings, display config, appearance changes, 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.

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 commands --json

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

Command Groups

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

| Group | Purpose | Example | |-------|---------|---------| | `omarchy refresh` | Reset config to defaults (backs up first) | `omarchy refresh shell` | | `omarchy restart` | Restart a service/app | `omarchy restart shell` | | `omarchy toggle` | Toggle feature on/off | `omarchy toggle nightlight` | | `omarchy theme` | Theme management | `omarchy theme set <name>` | | `omarchy bar` | Bar layout and widgets | `omarchy bar move omarchy.clock --section right` | | `omarchy plugin` | Manage/clone shell plugins | `omarchy plugin clone omarchy.clock` | | `omarchy hook` | Install automation hooks | `omarchy hook install theme-set <script>` | | `omarchy install` | Install optional software / packages | `omarchy install docker