omarchycn/default/omarchy-skill/SKILL.md

name, description

name

description

omarchy

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 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).

Critical Safety Rules

When invoking a privileged command directly, use pkexec instead of sudo so Omarchy can show a graphical authorization prompt with command context. 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 contains Omarchy's source files managed by git. Any changes will be:

• Lost on next omarchy update
• Cause conflicts with upstream
• Break the system's update mechanism

/usr/share/omarchy/     # READ-ONLY - NEVER EDIT (reading is OK)
├── bin/                    # Source scripts (symlinked to 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 (must be real directories)
• ~/.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	Quickshell launcher	~/.config/omarchy/shell.json
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
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 plugin move omarchy.clock --section right
omarchy plugin	Manage/clone shell plugins	omarchy plugin clone omarchy.clock local.clock --replace
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 (Window Manager)

Omarchy configures Hyprland in Lua. User files are loaded after Omarchy's defaults, so overrides go here:

~/.config/hypr/
├── hyprland.lua       # Main config (loads Omarchy defaults, then user files)
├── bindings.lua       # Keybindings
├── monitors.lua       # Display configuration
├── input.lua          # Keyboard/mouse settings
├── looknfeel.lua      # Appearance (gaps, borders, animations)
├── autostart.lua      # Startup applications
└── hyprsunset.conf    # Night light / blue light filter

Key behaviors:

• Hyprland auto-reloads on config save (no restart needed for most changes)
• Use hyprctl reload to force reload
• After ANY Hyprland config change, validate with hyprctl reload followed by hyprctl configerrors
• If hyprctl configerrors reports errors, address them and rerun validation until clean or until a real blocker is identified
• Use omarchy refresh hyprland to reset to defaults

Omarchy shell (Status Bar + Notifications)

The bar, notification daemon, settings panel, and assorted overlays all run inside a single long-running Quickshell process (omarchy-shell).

~/.config/omarchy/shell.json             # User overrides: bar, plugins, idle
~/.config/omarchy/plugins/<plugin-id>/   # User-owned shell plugins
$OMARCHY_PATH/config/omarchy/shell.json  # Canonical defaults

The shell hot-reloads shell.json on save — no restart needed for layout changes. idle.screensaver and idle.lock are seconds since user idle began.

To customize a built-in bar widget, never edit $OMARCHY_PATH/shell/plugins/. Clone it into the user plugin directory instead:

omarchy plugin clone omarchy.workspaces local.workspaces --replace
# Edit ~/.config/omarchy/plugins/local.workspaces/, then:
omarchy plugin rescan

Commands: omarchy restart shell, omarchy refresh shell

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

Pattern 1: Edit User Config Directly

For simple changes, edit files in ~/.config/:

# 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 hot-reloads; use `omarchy plugin rescan` for plugin/widget code changes
# - Launcher: restart with `omarchy restart shell`
# - Terminals: MUST restart with `omarchy restart terminal`

Pattern 2: Make a new theme

1. Create a directory under ~/.config/omarchy/themes.
2. See how an existing theme is done via /usr/share/omarchy/themes/catppuccin.
3. Download a matching background (or several) from the internet and put them in ~/.config/omarchy/themes/[name-of-new-theme]
4. When done with the theme, run omarchy theme set "Name of new theme"

Pattern 3: Use Hooks for Automation

Hooks live in ~/.config/omarchy/hooks/<name>.d/ — one directory per event, holding any number of independent scripts. Install with omarchy hook install <name> <script> (copies the script in and makes it executable):

~/.config/omarchy/hooks/
├── battery-low.d/          # Low battery (percentage in $1)
├── font-set.d/             # After font change (font name in $1)
├── post-boot.d/            # After the desktop starts
├── post-update.d/          # After `omarchy update`
├── pre-refresh-pacman.d/   # Before package sync during update
└── theme-set.d/            # After theme change (theme slug in $1)

Example hook script:

#!/bin/bash
THEME_NAME=$1
echo "Theme changed to: $THEME_NAME"
# Add custom actions here

Pattern 4: Reset to Defaults -- ALWAYS SEEK USER CONFIRMATION BEFORE RUNNING

When customizations go wrong:

# 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

Common Tasks

Themes

omarchy theme list              # Show available themes
omarchy theme current           # Show current theme
omarchy theme set <name>        # Apply theme ("Tokyo Night" and "tokyo-night" both work)
omarchy theme bg next           # Cycle background
omarchy theme install <url>     # Install from git repo

Keybindings

Edit ~/.config/hypr/bindings.lua. Format:

o.bind("SUPER + SHIFT + R", "SSH", "alacritty -e ssh your-server")
o.bind("SUPER + B", "Browser", { launch = "chromium" })  -- launch wraps with uwsm-app

View current bindings: omarchy menu keybindings --print

IMPORTANT: When re-binding an existing key:

1. First check existing bindings: omarchy menu keybindings --print
2. If the key is already bound, you MUST call hl.unbind(...) BEFORE the new o.bind(...)
3. Inform the user what the key was previously bound to

Example - rebinding SUPER+F (which is bound to fullscreen by default):

-- Unbind existing SUPER+F (was: fullscreen)
hl.unbind("SUPER + F")
-- New binding for file manager
o.bind("SUPER + F", "File manager", { launch = "nautilus" })

Always tell the user: "Note: SUPER+F was previously bound to fullscreen. I've added an unbind to override it."

Display/Monitors

Edit ~/.config/hypr/monitors.lua. Format:

hl.monitor({ output = "eDP-1", mode = "1920x1080@60", position = "0x0", scale = 1 })
hl.monitor({ output = "HDMI-A-1", mode = "2560x1440@144", position = "1920x0", scale = 1 })

List monitors and supported modes: hyprctl monitors all

Window Rules

CRITICAL: Hyprland window rules syntax changes frequently between versions.

Before writing ANY window rules, you MUST fetch the current documentation from the official Hyprland wiki:

• https://wiki.hypr.land/Configuring/Window-Rules/

DO NOT rely on cached or memorized window rule syntax. The format has changed multiple times and using outdated syntax will cause errors or unexpected behavior.

Window rules go in ~/.config/hypr/hyprland.lua or a required Lua module. Prefer Omarchy's o.window(match, rules) helper — see examples in $OMARCHY_PATH/default/hypr/windows.lua.

Fonts

omarchy font list               # Available fonts
omarchy font current            # Current font
omarchy font set <name>         # Change font

System

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

# 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? Create a NEW custom theme directory
4. Is it automation? 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? 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.

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
• "Set up night light to turn on at sunset" -> omarchy toggle nightlight or edit ~/.config/hypr/hyprsunset.conf
• "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" -> Create ~/.config/omarchy/themes/catppuccin-custom/ by copying from stock, then edit
• "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 to a user plugin with --replace, 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