omarchy

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 ANY file in ~/.config/waybar/, ~/.config/walker/, ~/.config/mako/
• 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 files in ~/.local/share/omarchy/, creating migrations, or running omarchy dev ... workflows).

Critical Safety Rules

For end-user customization tasks, 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: omarchy theme set --help or 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

If the request is to develop Omarchy itself, this skill is out of scope. Follow repository development instructions instead of this skill.

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/Foot/Kitty/Ghostty	Terminals	~/.config/<terminal>/
Mako	Notifications	~/.config/mako/
SwayOSD	On-screen display	~/.config/swayosd/

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 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 / 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 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
• 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

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/foot/foot.ini
~/.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/:

# 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, but MUST validate with `hyprctl reload` and `hyprctl configerrors`
# - 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

1. Create a directory under ~/.config/omarchy/themes.
2. See how an existing theme is done via ~/.local/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

Create scripts in ~/.config/omarchy/hooks/ to run automatically on events:

# 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):

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

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 bg next           # Cycle background
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:

1. First check existing bindings: omarchy menu keybindings --print
2. If the key is already bound, you MUST add an unbind directive BEFORE your new 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)
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 `~/.c

---

Content truncated.