omarchy Skill

1---2name: omarchy3description: >4  REQUIRED for end-user customization of Linux desktop, window manager, or system config.5  Use when editing ~/.config/hypr/, ~/.config/omarchy/,6  ~/.config/alacritty/, ~/.config/foot/, ~/.config/kitty/, or ~/.config/ghostty/.7  Triggers: Hyprland, window rules, animations, keybindings, monitors, gaps, borders,8  blur, opacity, omarchy-shell, bar, terminal config, themes, background,9  night light, idle, lock screen, screenshots, reminders, layer rules, workspace10  settings, display config, and user-facing omarchy commands. Excludes Omarchy11  source development through `omarchy dev link` workflows.12---13 14# Omarchy Skill15 16Manage [Omarchy](https://omarchy.org/) Linux systems - a beautiful, fun, agentic Arch Linux distribution with Hyprland.17 18This skill is for end-user customization on installed systems.19It is not for contributing to Omarchy source code.20 21## When This Skill MUST Be Used22 23**ALWAYS invoke this skill for end-user requests involving ANY of these:**24 25- Editing ANY file in `~/.config/hypr/` (window rules, animations, keybindings, monitors, etc.)26- Editing `~/.config/omarchy/shell.json` (status bar layout, widgets)27- Editing terminal configs (alacritty, foot, kitty, ghostty)28- Editing ANY file in `~/.config/omarchy/`29- Window behavior, animations, opacity, blur, gaps, borders30- Layer rules, workspace settings, display/monitor configuration31- Themes, backgrounds, fonts, appearance changes32- User-facing `omarchy` commands (`omarchy theme ...`, `omarchy refresh ...`, `omarchy restart ...`, etc.)33- Screenshots, screen recording, reminders, night light, idle behavior, lock screen34 35**If you're about to edit a config file in ~/.config/ on this system, STOP and use this skill first.**36 37**Do NOT use this skill for Omarchy development tasks** (editing the Omarchy source tree, creating migrations, or running `omarchy dev ...` workflows).38 39## Topic Guides40 41Deeper instructions for common areas live next to this file. Read the42matching guide before starting:43 44- [`hyprland.md`](hyprland.md) - keybindings, monitors, window rules, and other Hyprland config45- [`plugins.md`](plugins.md) - the Omarchy shell: bar layout, widgets, plugins, idle behavior46- [`theming.md`](theming.md) - themes, backgrounds, and fonts47- [`hooks.md`](hooks.md) - automation hooks that run on system events48- [`capture.md`](capture.md) - screenshots, screen recordings, OCR text capture, and file sharing49- [`contributing.md`](contributing.md) - reporting Omarchy bugs and submitting fixes upstream50 51## Critical Safety Rules52 53For 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.54 55**For end-user customization tasks, NEVER modify anything in `/usr/share/omarchy/`** - but READING is safe and encouraged.56 57This directory is owned by the omarchy package. Any local changes will be58overwritten on the next `omarchy update`.59 60```61/usr/share/omarchy/     # READ-ONLY - NEVER EDIT (reading is OK)62├── bin/                    # Command source (packaged binaries are on PATH)63├── config/                 # Default config templates64├── themes/                 # Stock themes65├── default/                # System defaults66├── shell/                  # Omarchy shell source and defaults67├── migrations/             # Update migrations68└── install/                # Installation scripts69```70 71**Reading `/usr/share/omarchy/` is SAFE and useful** - do it freely to:72- Understand how omarchy commands work: `omarchy theme set --help` or `cat $(which omarchy-theme-set)`73- See default configs before customizing: `cat "$OMARCHY_PATH/config/omarchy/shell.json"`74- Check stock theme files to copy for customization75- Reference default hyprland settings: `cat /usr/share/omarchy/default/hypr/*`76 77**Always use these safe locations instead:**78- `~/.config/` - User configuration (safe to edit)79- `~/.config/omarchy/themes/<custom-name>/` - Custom themes80- `~/.config/omarchy/hooks/` - Custom automation hooks81 82If the request is to develop Omarchy itself, this skill is out of scope. Follow repository development instructions instead of this skill.83 84## Privilege Escalation85 86For an interactive script or command run in a visible terminal, use `sudo` for87privileged work. Omarchy may grant passwordless `sudo` access to particular88commands, and the terminal is the appropriate place to request a password89when one is needed.90 91Use `pkexec` only when the caller cannot interact with a terminal or cannot92enter a password there, such as a command launched by an agent or a graphical93background process. Do not replace `sudo` with `pkexec` merely because a94command changes system state.95 96## System Architecture97 98Omarchy is built on:99 100| Component | Purpose | Config Location |101|-----------|---------|-----------------|102| **Arch Linux** | Base OS | `/etc/`, `~/.config/` |103| **Hyprland** | Wayland compositor/WM | `~/.config/hypr/` |104| **Omarchy shell** | Status bar + notifications (Quickshell) | `~/.config/omarchy/shell.json` |105| **Launcher/menus** | Quickshell menu | `~/.config/omarchy/extensions/omarchy-menu.jsonc` |106| **Alacritty/Foot/Kitty/Ghostty** | Terminals | `~/.config/<terminal>/` |107| **Omarchy OSD** | On-screen display | Quickshell plugin |108 109## Command Discovery110 111Omarchy 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.112 113```bash114# List every documented command and its summary (--all includes hidden commands)115omarchy commands116 117# Show the commands inside a group118omarchy theme --help119omarchy refresh --help120omarchy restart --help121 122# Show help for a specific command (does not execute it)123omarchy theme set --help124 125# Machine-readable listing (binary, route, summary, args, aliases)126omarchy commands --json127 128# Read a command's source to understand it129cat $(which omarchy-theme-set)130```131 132### Command Groups133 134Run `omarchy --help` for the full list. The most common groups:135 136| Group | Purpose | Example |137|-------|---------|---------|138| `omarchy refresh` | Reset config to defaults (backs up first) | `omarchy refresh shell` |139| `omarchy restart` | Restart a service/app | `omarchy restart shell` |140| `omarchy toggle` | Toggle feature on/off | `omarchy toggle nightlight` |141| `omarchy theme` | Theme management | `omarchy theme set <name>` |142| `omarchy bar` | Bar layout and widgets | `omarchy bar move omarchy.clock --section right` |143| `omarchy plugin` | Manage/clone shell plugins | `omarchy plugin clone omarchy.clock` |144| `omarchy hook` | Install automation hooks | `omarchy hook install theme-set <script>` |145| `omarchy install` | Install optional software / packages | `omarchy install docker dbs` |146| `omarchy launch` | Launch apps | `omarchy launch browser` |147| `omarchy capture` | Screenshots and recordings | `omarchy capture screenshot` |148| `omarchy reminder` | Desktop notification reminders | `omarchy reminder 15 "Pickup Jack"` |149| `omarchy pkg` | Package management | `omarchy pkg add <pkg>` |150| `omarchy setup` | Interactive setup wizards | `omarchy setup security fingerprint` |151| `omarchy update` | System updates | `omarchy update` |152 153## Configuration Locations154 155Hyprland config lives in `~/.config/hypr/` — see [`hyprland.md`](hyprland.md).156The Omarchy shell (bar, notifications, plugins, idle) is configured in157`~/.config/omarchy/shell.json` — see [`plugins.md`](plugins.md).158 159### Terminals160 161```162~/.config/alacritty/alacritty.toml163~/.config/foot/foot.ini164~/.config/kitty/kitty.conf165~/.config/ghostty/config166```167 168**Command:** `omarchy restart terminal`169 170### Other Configs171 172| App | Location |173|-----|----------|174| btop | `~/.config/btop/btop.conf` |175| fastfetch | `/etc/fastfetch/config.jsonc` default; `~/.config/fastfetch/config.jsonc` user override |176| lazygit | `~/.config/lazygit/config.yml` |177| starship | `~/.config/starship.toml` |178| git | `~/.config/git/config` |179 180## Safe Customization Patterns181 182### Edit User Config Directly183 184For simple changes, edit files in `~/.config/`:185 186```bash187# 1. Read current config188cat ~/.config/hypr/bindings.lua189 190# 2. Backup before changes191cp ~/.config/hypr/bindings.lua ~/.config/hypr/bindings.lua.bak.$(date +%s)192 193# 3. Make changes with Edit tool194 195# 4. Apply changes196# - Hyprland: auto-reloads on save, but MUST validate with `hyprctl reload` and `hyprctl configerrors`197# - Omarchy shell: shell.json and user plugin code under ~/.config/omarchy/plugins/ hot-reload on save198# - Menus/launcher: ~/.config/omarchy/extensions/omarchy-menu.jsonc hot-reloads on save199# - Terminals: apply with `omarchy restart terminal` (reloads running terminals; foot picks changes up in new windows)200```201 202### Reset to Defaults -- ALWAYS SEEK USER CONFIRMATION BEFORE RUNNING203 204When customizations go wrong:205 206```bash207# Reset specific config (creates backup automatically)208omarchy refresh shell209omarchy refresh hyprland210 211# The refresh command:212# 1. Backs up current config with timestamp213# 2. Copies default from $OMARCHY_PATH/config/214# 3. Restarts the component where the refresh needs it (e.g. `refresh shell`)215```216 217## System Commands218 219```bash220omarchy update                  # Full system update221omarchy version                 # Show Omarchy version222omarchy debug --no-sudo --print # Debug info (ALWAYS use these flags)223omarchy system lock             # Lock screen224omarchy system shutdown         # Shutdown225omarchy system reboot           # Reboot226```227 228**IMPORTANT:** Always run `omarchy debug` with `--no-sudo --print` flags to avoid interactive sudo prompts that will hang the terminal.229 230## Troubleshooting231 232```bash233# Get debug information (ALWAYS use these flags to avoid interactive prompts)234omarchy debug --no-sudo --print235 236# Reset specific config to defaults237omarchy refresh <app>238 239# Refresh specific config file240# config-file path is relative to ~/.config/241# eg. `omarchy refresh config hypr/hyprland.lua` will refresh ~/.config/hypr/hyprland.lua242omarchy refresh config <config-file>243 244# Full reinstall of configs (nuclear option)245omarchy reinstall246```247 248## Decision Framework249 250When user requests system changes:251 2521. **Is it a stock omarchy command?** Use it directly2532. **Is it a config edit?** Edit in `~/.config/`, never `/usr/share/omarchy/`2543. **Is it a theme customization?** Follow [`theming.md`](theming.md); create a NEW custom theme directory2554. **Is it automation?** Follow [`hooks.md`](hooks.md); use `omarchy hook install` and the hook `.d` directories2565. **Is it a package install?** Use `omarchy pkg add <pkgs...>` (or `omarchy pkg aur add <pkgs...>` for AUR-only packages)2576. **Is it built-in shell/plugin code?** Follow [`plugins.md`](plugins.md); clone it with `omarchy plugin clone`, never edit the packaged copy2587. **Unsure if command exists?** Run `omarchy commands` (or `omarchy <group> --help` for one group)259 260### Reminder Requests261 262When the user asks to set a reminder, use `omarchy reminder <minutes> [message]` directly. Convert natural language durations to minutes and title-case short reminder labels when appropriate.263 264```bash265omarchy reminder 15 "Pickup Jack"266omarchy reminder 60 "Check laundry"267omarchy reminder show268omarchy reminder clear269```270 271## Out of Scope272 273This skill intentionally does not cover Omarchy source development. Do not use this skill for:274- Editing files in `/usr/share/omarchy/` (`bin/`, `config/`, `default/`, `shell/`, `themes/`, `migrations/`, etc.)275- Creating or editing migrations276- Running `omarchy dev ...` commands277 278## Example Requests279 280- "Change my theme to catppuccin" -> `omarchy theme set catppuccin`281- "Add a keybinding for Super+E to open file manager" -> Check existing bindings first, then use `o.rebind` to replace one or `o.bind` to add one in `~/.config/hypr/bindings.lua`282- "Configure my external monitor" -> Edit `~/.config/hypr/monitors.lua`283- "Make the window gaps smaller" -> Edit `~/.config/hypr/looknfeel.lua`284- "Turn on night light" -> `omarchy toggle nightlight` (for time-based schedules, edit `~/.config/hypr/hyprsunset.conf` profiles, then `omarchy restart hyprsunset`)285- "Set a reminder to pickup jack in 15 minutes" -> `omarchy reminder 15 "Pickup Jack"`286- "Show my reminders" -> `omarchy reminder show`287- "Clear all reminders" -> `omarchy reminder clear`288- "Customize the catppuccin theme colors" -> Overlay: put an edited `colors.toml` in `~/.config/omarchy/themes/catppuccin/`, then re-apply the theme (see `theming.md`)289- "Run a script every time I change themes" -> Install it with `omarchy hook install theme-set <script>`290- "Change how workspace labels are rendered" -> Clone `omarchy.workspaces`, which switches the bar to `<username>.workspaces`, then edit the clone291- "Lock after ten minutes" -> Set `idle.lock` to `600` in `~/.config/omarchy/shell.json`292- "Reset shell/bar to defaults" -> `omarchy refresh shell`293- "Record my screen" -> `omarchy screenrecord --fullscreen`, then `omarchy screenrecord --stop-recording` (see `capture.md`)294- "Report this bug to Omarchy" -> Gather diagnostics and a capture of the problem, then file it (see `contributing.md`)295