Omarchy Skill

Manage Omarchy Linux systems - a beautiful, modern, opinionated Arch Linux distribution with Hyprland.

When This Skill MUST Be Used

ALWAYS invoke this skill when the user's request involves ANY of these:

Editing ANY file in
```
~/.config/hypr/
```
(window rules, animations, keybindings, monitors, etc.)

Editing ANY file in

~/.config/waybar/

~/.config/walker/

~/.config/mako/

Editing terminal configs (alacritty, kitty, ghostty)
Editing ANY file in
```
~/.config/omarchy/
```
Window behavior, animations, opacity, blur, gaps, borders
Layer rules, workspace settings, display/monitor configuration
Themes, wallpapers, fonts, appearance changes
Any
```
omarchy-*
```
command
Screenshots, screen recording, 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.

Critical Safety Rules

NEVER modify anything in
~/.local/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

~/.local/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
├── migrations/             # Update migrations
└── install/                # Installation scripts

Reading
~/.local/share/omarchy/
is SAFE and useful - do it freely to:

Understand how omarchy commands work:
```
cat $(which omarchy-theme-set)
```

See default configs before customizing:

cat ~/.local/share/omarchy/config/waybar/config.jsonc

Check stock theme files to copy for customization

Reference default hyprland settings:

cat ~/.local/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

System Architecture

Omarchy is built on:

Component	Purpose	Config Location
Arch Linux	Base OS	`/etc/` , `~/.config/`
Hyprland	Wayland compositor/WM	`~/.config/hypr/`
Waybar	Status bar	`~/.config/waybar/`
Walker	App launcher	`~/.config/walker/`
Alacritty/Kitty/Ghostty	Terminals	`~/.config/<terminal>/`
Mako	Notifications	`~/.config/mako/`
SwayOSD	On-screen display	`~/.config/swayosd/`

Command Discovery

Omarchy provides ~145 commands following

omarchy-<category>-<action>

pattern.

bash

# List all omarchy commands
compgen -c | grep -E '^omarchy-' | sort -u

# Find commands by category
compgen -c | grep -E '^omarchy-theme'
compgen -c | grep -E '^omarchy-restart'

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

Command Categories

Prefix	Purpose	Example
`omarchy-refresh-*`	Reset config to defaults (backs up first)	`omarchy-refresh-waybar`
`omarchy-restart-*`	Restart a service/app	`omarchy-restart-waybar`
`omarchy-toggle-*`	Toggle feature on/off	`omarchy-toggle-nightlight`
`omarchy-theme-*`	Theme management	`omarchy-theme-set <name>`
`omarchy-install-*`	Install optional software	`omarchy-install-docker-dbs`
`omarchy-launch-*`	Launch apps	`omarchy-launch-browser`
`omarchy-cmd-*`	System commands	`omarchy-cmd-screenshot`
`omarchy-pkg-*`	Package management	`omarchy-pkg-install <pkg>`
`omarchy-setup-*`	Initial setup tasks	`omarchy-setup-fingerprint`
`omarchy-update-*`	System updates	`omarchy-update`

Configuration Locations

Hyprland (Window Manager)

~/.config/hypr/
├── hyprland.conf      # Main config (sources others)
├── bindings.conf      # Keybindings
├── monitors.conf      # Display configuration
├── input.conf         # Keyboard/mouse settings
├── looknfeel.conf     # Appearance (gaps, borders, animations)
├── envs.conf          # Environment variables
├── autostart.conf     # Startup applications
├── hypridle.conf      # Idle behavior (screen off, lock, suspend)
├── hyprlock.conf      # Lock screen appearance
└── 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
Use
```
omarchy-refresh-hyprland
```
to reset to defaults

Waybar (Status Bar)

~/.config/waybar/
├── config.jsonc       # Bar layout and modules (JSONC format)
└── style.css          # Styling

Waybar does NOT auto-reload. You MUST run

omarchy-restart-waybar

after any config changes.

Commands:

omarchy-restart-waybar

omarchy-refresh-waybar

omarchy-toggle-waybar

Terminals

~/.config/alacritty/alacritty.toml
~/.config/kitty/kitty.conf
~/.config/ghostty/config

Command:

omarchy-restart-terminal

Other Configs

App	Location
btop	`~/.config/btop/btop.conf`
fastfetch	`~/.config/fastfetch/config.jsonc`
lazygit	`~/.config/lazygit/config.yml`
starship	`~/.config/starship.toml`
git	`~/.config/git/config`
walker	`~/.config/walker/config.toml`

Safe Customization Patterns

Pattern 1: Edit User Config Directly

For simple changes, edit files in

~/.config/

bash

# 1. Read current config
cat ~/.config/hypr/bindings.conf

# 2. Backup before changes
cp ~/.config/hypr/bindings.conf ~/.config/hypr/bindings.conf.bak.$(date +%s)

# 3. Make changes with Edit tool

# 4. Apply changes
# - Hyprland: auto-reloads on save (no restart needed)
# - Waybar: MUST restart with omarchy-restart-waybar
# - Walker: MUST restart with omarchy-restart-walker
# - Terminals: MUST restart with omarchy-restart-terminal

Pattern 2: Make a new theme

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

Pattern 3: Use Hooks for Automation

Create scripts in

~/.config/omarchy/hooks/

to run automatically on events:

bash

# Available hooks (see samples in ~/.config/omarchy/hooks/):
~/.config/omarchy/hooks/
├── theme-set        # Runs after theme change (receives theme name as $1)
├── font-set         # Runs after font change
└── post-update      # Runs after omarchy-update

Example hook (

~/.config/omarchy/hooks/theme-set

bash

#!/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:

bash

# Reset specific config (creates backup automatically)
omarchy-refresh-waybar
omarchy-refresh-hyprland

# The refresh command:
# 1. Backs up current config with timestamp
# 2. Copies default from ~/.local/share/omarchy/config/
# 3. Restarts the component

Common Tasks

Themes

bash

omarchy-theme-list              # Show available themes
omarchy-theme-current           # Show current theme
omarchy-theme-set <name>        # Apply theme (use "Tokyo Night" not "tokyo-night")
omarchy-theme-next              # Cycle to next theme
omarchy-theme-bg-next           # Cycle wallpaper
omarchy-theme-install <url>     # Install from git repo

Keybindings

Edit

~/.config/hypr/bindings.conf

. Format:

bind = SUPER, Return, exec, xdg-terminal-exec
bind = SUPER, Q, killactive
bind = SUPER SHIFT, E, exit

View current bindings:

omarchy-menu-keybindings --print

IMPORTANT: When re-binding an existing key:

First check existing bindings:
```
omarchy-menu-keybindings --print
```
If the key is already bound, you MUST add an
```
unbind
```
directive BEFORE your new
```
bind
```
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)
unbind = SUPER, F
# New binding for file manager
bind = SUPER, F, exec, nautilus

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

Display/Monitors

Edit

~/.config/hypr/monitors.conf

. Format:

monitor = eDP-1, 1920x1080@60, 0x0, 1
monitor = HDMI-A-1, 2560x1440@144, 1920x0, 1

List monitors:

hyprctl monitors

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://github.com/hyprwm/hyprland-wiki/blob/main/content/Configuring/Window-Rules.md

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

or a sourced file. Always verify the current syntax from the wiki first.

Fonts

bash

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

System

bash

omarchy-update                  # Full system update
omarchy-version                 # Show Omarchy version
omarchy-debug --no-sudo --print # Debug info (ALWAYS use these flags)
omarchy-lock-screen             # Lock screen
omarchy-cmd-shutdown            # Shutdown
omarchy-cmd-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

# Upload logs for support
omarchy-upload-log

# Reset specific config to defaults
omarchy-refresh-<app>

# Refresh specific config file
# config-file path is relative to ~/.config/
# eg. omarchy-refresh-config hypr/hyprlock.conf will refresh ~/.config/hypr/hyprlock.conf
omarchy-refresh-config <config-file>

# Full reinstall of configs (nuclear option)
omarchy-reinstall

Decision Framework

When user requests system changes:

Is it a stock omarchy command? Use it directly
Is it a config edit? Edit in
```
~/.config/
```
, never
```
~/.local/share/omarchy/
```
Is it a theme customization? Create a NEW custom theme directory
Is it automation? Use hooks in
```
~/.config/omarchy/hooks/
```
Is it a package install? Use
```
yay
```
Unsure if command exists? Search with
```
compgen -c | grep omarchy
```

Development (AI Agents)

When contributing to Omarchy itself (e.g., fixing bugs, adding features), migrations are used to apply changes to existing installations.

Creating Migrations

bash

# ALWAYS use --no-edit flag or you will get stuck
omarchy-dev-add-migration --no-edit

This creates a new migration file and outputs its path without opening an editor. The migration filename is based on the git commit timestamp.

Migration files are shell scripts in

~/.local/share/omarchy/migrations/

that run once per system during

omarchy-update

. Use them for:

Updating user configs with new defaults
Installing new dependencies
Running one-time setup tasks

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, add
```
unbind
```
if needed, then add
```
bind
```
in
```
~/.config/hypr/bindings.conf
```
"Configure my external monitor" -> Edit
```
~/.config/hypr/monitors.conf
```
"Make the window gaps smaller" -> Edit
```
~/.config/hypr/looknfeel.conf
```

"Set up night light to turn on at sunset" ->

omarchy-toggle-nightlight

or edit

~/.config/hypr/hyprsunset.conf

"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" -> Create
```
~/.config/omarchy/hooks/theme-set
```
"Reset waybar to defaults" ->
```
omarchy-refresh-waybar
```

omarchy

NPX Install

Tags

SKILL.md Content

Omarchy Skill

When This Skill MUST Be Used

Critical Safety Rules

System Architecture

Command Discovery

Command Categories

Configuration Locations

Hyprland (Window Manager)

Waybar (Status Bar)

Terminals

Other Configs

Safe Customization Patterns

Pattern 1: Edit User Config Directly

Pattern 2: Make a new theme

Pattern 3: Use Hooks for Automation

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

Common Tasks

Themes

Keybindings

Display/Monitors

Window Rules

Fonts

System

Troubleshooting

Decision Framework

Development (AI Agents)

Creating Migrations

Example Requests