omarchy

# Omarchy Skill Manage [Omarchy](https://omarchy.org/) Linux systems - a beautiful, modern, opinionated 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. ```bash # 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 dbs` | | `omarchy launch` | Launch apps | `omarchy launch browser` | | `omarchy capture` | Screenshots and recordings | `omarchy capture screenshot` | | `omarchy reminder` | Desktop notification reminders | `omarchy reminder 15 "Pickup Jack"` | | `omarchy pkg` | Package management | `omarchy pkg add <pkg>` | | `omarchy setup` | Interactive setup wizards | `omarchy setup security fingerprint` | | `omarchy update` | System updates | `omarchy update` | ## Configuration Locations Hyprland config lives in `~/.config/hypr/` — see [`hyprland.md`](hyprland.md). The Omarchy shell (bar, notifications, plugins, idle) is configured in `~/.config/omarchy/shell.json` — see [`plugins.md`](plugins.md). ### Terminals ``` ~/.config/alacritty/alacritty.toml ~/.config/foot/foot.ini ~/.config/kitty/kitty.conf ~/.config/ghostty/config ``` **Command:** `omarchy restart terminal` ### Other Configs | App | Location | |-----|----------| | btop | `~/.config/btop/btop.conf` | | fastfetch | `/etc/fastfetch/config.jsonc` default; `~/.config/fastfetch/config.jsonc` user override | | lazygit | `~/.config/lazygit/config.yml` | | starship | `~/.config/starship.toml` | | git | `~/.config/git/config` | ## Safe Customization Patterns ### Edit User Config Directly For simple changes, edit files in `~/.config/`: ```bash # 1. Read current config cat ~/.config/hypr/bindings.lua # 2. Backup before changes cp ~/.config/hypr/bindings.lua ~/.config/hypr/bindings.lua.bak.$(date +%s) # 3. Make changes with Edit tool # 4. Apply changes # - Hyprland: auto-reloads on save, but MUST validate with `hyprctl reload` and `hyprctl configerrors` # - Omarchy shell: shell.json and user plugin code under ~/.config/omarchy/plugins/ hot-reload on save # - Menus/launcher: ~/.config/omarchy/extensions/omarchy-menu.jsonc hot-reloads on save # - Terminals: apply with `omarchy restart terminal` (reloads running terminals; foot picks changes up in new windows) ``` ### Reset to Defaults -- ALWAYS SEEK USER CONFIRMATION BEFORE RUNNING When customizations go wrong: ```bash # Reset specific config (creates backup automatically) omarchy refresh shell omarchy refresh hyprland # The refresh command: # 1. Backs up current config with timestamp # 2. Copies default from $OMARCHY_PATH/config/ # 3. Restarts the component where the refresh needs it (e.g. `refresh shell`) ``` ## System Commands ```bash omarchy update # Full system update omarchy version # Show Omarchy version omarchy debug --no-sudo --print # Debug info (ALWAYS use these flags) omarchy system lock # Lock screen omarchy system shutdown # Shutdown omarchy system reboot # Reboot ``` **IMPORTANT:** Always run `omarchy debug` with `--no-sudo --print` flags to avoid interactive sudo prompts that will hang the terminal. ## Troubleshooting ```bash # Get debug information (ALWAYS use these flags to avoid interactive prompts) omarchy debug --no-sudo --print # Reset specific config to defaults omarchy refresh <app> # Refresh specific config file # config-file path is relative to ~/.config/ # eg. `omarchy refresh config hypr/hyprland.lua` will refresh ~/.config/hypr/hyprland.lua omarchy refresh config <config-file> # Full reinstall of configs (nuclear option) omarchy reinstall ``` ## Decision Framework When user requests system changes: 1. **Is it a stock omarchy command?** Use it directly 2. **Is it a config edit?** Edit in `~/.config/`, never `/usr/share/omarchy/` 3. **Is it a theme customization?** Follow [`theming.md`](theming.md); create a NEW custom theme directory 4. **Is it automation?** Follow [`hooks.md`](hooks.md); use `omarchy hook install` and the hook `.d` directories 5. **Is it a package install?** Use `omarchy pkg add <pkgs...>` (or `omarchy pkg aur add <pkgs...>` for AUR-only packages) 6. **Is it built-in shell/plugin code?** Follow [`plugins.md`](plugins.md); clone it with `omarchy plugin clone`, never edit the packaged copy 7. **Unsure if command exists?** Run `omarchy commands` (or `omarchy <group> --help` for one group) ### Reminder Requests When 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. ```bash omarchy reminder 15 "Pickup Jack" omarchy reminder 60 "Check laundry" omarchy reminder show omarchy reminder clear ``` ## Out of Scope This skill intentionally does not cover Omarchy source development. Do not use this skill for: - Editing files in `/usr/share/omarchy/` (`bin/`, `config/`, `default/`, `shell/`, `themes/`, `migrations/`, etc.) - Creating or editing migrations - Running `omarchy dev ...` commands ## Example Requests - "Change my theme to catppuccin" -> `omarchy theme set catppuccin` - "Add a keybinding for Super+E to open file manager" -> Check existing bindings first, call `hl.unbind` if needed, then `o.bind` in `~/.config/hypr/bindings.lua` - "Configure my external monitor" -> Edit `~/.config/hypr/monitors.lua` - "Make the window gaps smaller" -> Edit `~/.config/hypr/looknfeel.lua` - "Turn on night light" -> `omarchy toggle nightlight` (for time-based schedules, edit `~/.config/hypr/hyprsunset.conf` profiles, then `omarchy restart hyprsunset`) - "Set a reminder to pickup jack in 15 minutes" -> `omarchy reminder 15 "Pickup Jack"` - "Show my reminders" -> `omarchy reminder show` - "Clear all reminders" -> `omarchy reminder clear` - "Customize the catppuccin theme colors" -> Overlay: put an edited `colors.toml` in `~/.config/omarchy/themes/catppuccin/`, then re-apply the theme (see `theming.md`) - "Run a script every time I change themes" -> Install it with `omarchy hook install theme-set <script>` - "Change how workspace labels are rendered" -> Clone `omarchy.workspaces`, which switches the bar to `<username>.workspaces`, then edit the clone - "Lock after ten minutes" -> Set `idle.lock` to `600` in `~/.config/omarchy/shell.json` - "Reset shell/bar to defaults" -> `omarchy refresh shell` - "Record my screen" -> `omarchy screenrecord --fullscreen`, then `omarchy screenrecord --stop-recording` (see `capture.md`) - "Report this bug to Omarchy" -> Gather diagnostics and a capture of the problem, then file it (see `contributing.md`)