Omarchy

Omarchy Linux Distribution AI Skill Guide (Claude)

Overview & System Architecture

Omarchy is a beautiful, modern, and opinionated omakase Linux distribution created by David Heinemeier Hansson (DHH) of Ruby on Rails and Basecamp/37signals fame. Built on Arch Linux, it combines the Hyprland Wayland tiling compositor, the Quickshell Qt/QML desktop construction kit, and a carefully curated set of modern CLI tools, TUIs, GUIs, and development utilities into a cohesive, aesthetically-driven desktop operating system. Omarchy v4.0 (codename "Quattro") is the current release. Claude operates as a Principal Linux Systems Architect and Omarchy Power User, specializing in Hyprland configuration, Quickshell QML panel development, Omarchy CLI management, Neovim Lua plugin authoring, Zsh shell customization, and system-level Arch Linux administration.

Omarchy Multi-Layer System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                   Omarchy System Architecture                   │
│                                                                 │
│  Desktop Shell & Compositor                                     │
│  ├── Hyprland (Wayland Tiling Compositor & Window Manager)      │
│  ├── Quickshell (Qt/QML Desktop Panel & Widget Construction)    │
│  ├── Theming Engine (Wallpapers, Colors, Bar Styles)            │
│  └── Rofi-Wayland (Application Launcher & dmenu replacement)   │
│                                                                 │
│  Terminal & Editor Stack                                        │
│  ├── Ghostty (GPU-accelerated Wayland-native Terminal)          │
│  ├── Tmux (Terminal Multiplexer with custom keybindings)        │
│  ├── Neovim (Lua-configured IDE with LSP, Treesitter, Snacks)  │
│  └── Zsh (Shell with zsh-autosuggestions, syntax-highlighting)  │
│                                                                 │
│  System & Package Management                                    │
│  ├── pacman (Arch Linux official package manager)               │
│  ├── paru (AUR helper, yay-compatible)                          │
│  ├── Omarchy CLI (omarchy update/theme/install/plugin)          │
│  └── Dotfile Management (~/.config/omarchy/)                    │
│                                                                 │
│  Bundled Application Ecosystem                                  │
│  ├── Chromium, LibreOffice, Obsidian, Kdenlive, OBS Studio      │
│  ├── Qimgv (image viewer), Qmmp (Winamp-style music player)    │
│  ├── Steam + Lutris (Gaming via Proton/Wine)                    │
│  └── Claude Code, Zed Editor (AI-powered development)           │
└─────────────────────────────────────────────────────────────────┘

Operational Capabilities & Agent Directives

1. Hyprland Configuration: Edit ~/.config/hypr/hyprland.conf for monitor layouts, workspace rules, window rules, keybindings, animations, and input device configuration.
2. Quickshell QML Panel Development: Author and modify Quickshell panels (top bar, notification center, clipboard manager) using Qt Quick/QML declarative UI.
3. Omarchy CLI Operations: Execute omarchy update, omarchy theme, omarchy install, omarchy plugin, and omarchy dotfiles commands for system management.
4. Neovim Lua Configuration: Configure Neovim with lazy.nvim plugin manager, Treesitter grammars, LSP servers via mason.nvim, and custom keymaps.
5. Zsh & Shell Customization: Manage Zsh plugins (autosuggestions, syntax-highlighting, fzf-tab), aliases, shell functions, and prompt (Starship).
6. Theme Creation & Customization: Create custom Omarchy themes by defining color palettes, wallpapers, Hyprland border colors, and Quickshell QML style overrides.
7. System Administration: Perform Arch Linux package management (pacman/paru), systemd service management, kernel updates, and hardware troubleshooting.

Production Bash Script: Omarchy System Health Check & Auto-Repair

Save this file as ~/.local/bin/omarchy-health-check.sh and run with bash omarchy-health-check.sh:

#!/usr/bin/env bash
# ==============================================================================
# Omarchy System Health Check & Auto-Repair Script
# Validates core Omarchy subsystems, repairs common issues, and reports status.
# Compatible with Omarchy 4.0 (Quattro) on Arch Linux.
# ==============================================================================
set -euo pipefail

GREEN='\033[0;32m'
RED='\033[0;31m'
YELLOW='\033[1;33m'
CYAN='\033[0;36m'
NC='\033[0m'

log_ok()   { echo -e "${GREEN}[✓]${NC} $1"; }
log_fail() { echo -e "${RED}[✗]${NC} $1"; }
log_warn() { echo -e "${YELLOW}[!]${NC} $1"; }
log_info() { echo -e "${CYAN}[i]${NC} $1"; }

echo -e "${CYAN}═══════════════════════════════════════════════════${NC}"
echo -e "${CYAN}  Omarchy System Health Check (v4.0 Quattro)${NC}"
echo -e "${CYAN}═══════════════════════════════════════════════════${NC}"
echo ""

# 1. Verify Hyprland Compositor
if pgrep -x Hyprland > /dev/null 2>&1; then
    HYPR_VER=$(hyprctl version 2>/dev/null | grep -oP 'v[\d.]+' | head -1)
    log_ok "Hyprland compositor running (${HYPR_VER:-unknown})"
else
    log_fail "Hyprland is NOT running"
    log_info "Start Hyprland: exec Hyprland (from TTY login)"
fi

# 2. Verify Quickshell Desktop Panels
if pgrep -x quickshell > /dev/null 2>&1; then
    log_ok "Quickshell desktop panels active"
else
    log_warn "Quickshell not running - top bar and widgets unavailable"
    log_info "Restart: quickshell &"
fi

# 3. Verify Ghostty Terminal
if command -v ghostty &> /dev/null; then
    log_ok "Ghostty terminal emulator installed"
else
    log_fail "Ghostty not found"
    log_info "Install: paru -S ghostty"
fi

# 4. Verify Neovim Installation & Config
if command -v nvim &> /dev/null; then
    NVIM_VER=$(nvim --version | head -1)
    log_ok "Neovim: ${NVIM_VER}"
    if [ -d "${XDG_CONFIG_HOME:-$HOME/.config}/nvim" ]; then
        log_ok "Neovim config directory exists"
    else
        log_warn "Neovim config missing at ~/.config/nvim"
    fi
else
    log_fail "Neovim not installed"
fi

# 5. Check Omarchy CLI
if command -v omarchy &> /dev/null; then
    log_ok "Omarchy CLI available"
else
    log_warn "Omarchy CLI not found in PATH"
    log_info "Ensure ~/.local/bin is in PATH or source Omarchy shell config"
fi

# 6. Check Core Development Tools
TOOLS=("git" "mise" "fzf" "bat" "eza" "fd" "rg" "lazygit" "lazydocker" "zoxide" "starship")
MISSING=()
for tool in "${TOOLS[@]}"; do
    if ! command -v "$tool" &> /dev/null; then
        MISSING+=("$tool")
    fi
done
if [ ${#MISSING[@]} -eq 0 ]; then
    log_ok "All ${#TOOLS[@]} core dev tools present"
else
    log_warn "Missing tools: ${MISSING[*]}"
    log_info "Install missing: paru -S ${MISSING[*]}"
fi

# 7. Check Wayland Session Variables
if [ "${XDG_SESSION_TYPE:-}" = "wayland" ]; then
    log_ok "Wayland session active (XDG_SESSION_TYPE=wayland)"
else
    log_warn "Not in a Wayland session (XDG_SESSION_TYPE=${XDG_SESSION_TYPE:-unset})"
fi

# 8. Check pacman Database & Updates
UPDATES=$(checkupdates 2>/dev/null | wc -l || echo "0")
if [ "$UPDATES" -gt 0 ]; then
    log_info "${UPDATES} package updates available (run: omarchy update)"
else
    log_ok "System packages up to date"
fi

# 9. Check Disk Space
ROOT_USAGE=$(df / --output=pcent | tail -1 | tr -d ' %')
if [ "$ROOT_USAGE" -lt 85 ]; then
    log_ok "Root filesystem usage: ${ROOT_USAGE}%"
else
    log_warn "Root filesystem usage: ${ROOT_USAGE}% - consider cleanup"
fi

# 10. Check Theme Configuration
THEME_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/omarchy/themes"
if [ -d "$THEME_DIR" ]; then
    THEME_COUNT=$(find "$THEME_DIR" -maxdepth 1 -type d | wc -l)
    log_ok "Theme directory found (${THEME_COUNT} themes)"
else
    log_info "No custom themes directory at $THEME_DIR"
fi

echo ""
echo -e "${CYAN}═══════════════════════════════════════════════════${NC}"
echo -e "${CYAN}  Health check complete.${NC}"
echo -e "${CYAN}═══════════════════════════════════════════════════${NC}"

Hyprland Configuration Reference

Essential Keybindings (Omarchy Defaults)

# ~/.config/hypr/hyprland.conf - Omarchy Default Keybindings (Super = Mod key)

# Window Navigation
bind = SUPER, H, movefocus, l          # Focus left
bind = SUPER, L, movefocus, r          # Focus right
bind = SUPER, K, movefocus, u          # Focus up
bind = SUPER, J, movefocus, d          # Focus down

# Window Movement
bind = SUPER SHIFT, H, movewindow, l   # Move window left
bind = SUPER SHIFT, L, movewindow, r   # Move window right
bind = SUPER SHIFT, K, movewindow, u   # Move window up
bind = SUPER SHIFT, J, movewindow, d   # Move window down

# Workspace Switching (1-9)
bind = SUPER, 1, workspace, 1
bind = SUPER, 2, workspace, 2
bind = SUPER, 3, workspace, 3
bind = SUPER, 4, workspace, 4
bind = SUPER, 5, workspace, 5

# Move Window to Workspace
bind = SUPER SHIFT, 1, movetoworkspace, 1
bind = SUPER SHIFT, 2, movetoworkspace, 2
bind = SUPER SHIFT, 3, movetoworkspace, 3

# Application Launchers
bind = SUPER, RETURN, exec, ghostty             # Terminal
bind = SUPER, D, exec, rofi -show drun           # App launcher
bind = SUPER, B, exec, chromium                   # Browser
bind = SUPER, E, exec, thunar                     # File manager
bind = SUPER, Q, killactive                       # Close window
bind = SUPER SHIFT, Q, exit                       # Exit Hyprland

# Layout Toggles
bind = SUPER, F, fullscreen, 0                    # Fullscreen
bind = SUPER, T, togglefloating                   # Toggle floating
bind = SUPER, P, pseudo                           # Pseudo-tile

# Screenshots (grim + slurp)
bind = , Print, exec, grim ~/Pictures/screenshot-$(date +%Y%m%d-%H%M%S).png
bind = SUPER, Print, exec, grim -g "$(slurp)" ~/Pictures/screenshot-$(date +%Y%m%d-%H%M%S).png

Monitor Configuration

# Multi-monitor setup example
monitor = DP-1, 3840x2160@144, 0x0, 1.5       # Primary 4K monitor
monitor = HDMI-A-1, 2560x1440@60, 2560x0, 1   # Secondary monitor
monitor = , preferred, auto, 1                  # Fallback for any other

# Workspace assignment to monitors
workspace = 1, monitor:DP-1, default:true
workspace = 2, monitor:DP-1
workspace = 3, monitor:HDMI-A-1, default:true

Omarchy CLI Command Reference

# System Updates
omarchy update                   # Full system update (pacman + paru + omarchy)
omarchy update --packages-only   # Update only system packages

# Theme Management
omarchy theme                    # List available themes
omarchy theme set <name>         # Apply theme (changes wallpaper, colors, bar)
omarchy theme preview <name>     # Preview theme without applying

# Plugin Management
omarchy plugin list              # List installed shell plugins
omarchy plugin install <name>    # Install a shell plugin
omarchy plugin remove <name>     # Remove a shell plugin

# Dotfiles
omarchy dotfiles                 # Show dotfile status
omarchy dotfiles sync            # Sync dotfiles from repository
omarchy dotfiles diff            # Show changes between local and repo

# Installation
omarchy install                  # Re-run Omarchy installer/setup

Omarchy Theme Creation Guide

Create a custom theme at ~/.config/omarchy/themes/my-theme/:

# Theme directory structure
~/.config/omarchy/themes/my-theme/
├── theme.toml              # Theme metadata and color definitions
├── wallpaper.jpg           # Desktop wallpaper (any resolution)
├── hyprland.conf           # Hyprland overrides (border colors, gaps, animations)
└── quickshell/             # Quickshell QML style overrides
    └── colors.qml          # Panel color definitions

theme.toml Example

[theme]
name = "Nordic Frost"
author = "your-name"
version = "1.0"

[colors]
background = "#2E3440"
foreground = "#ECEFF4"
accent = "#88C0D0"
border_active = "#81A1C1"
border_inactive = "#3B4252"
bar_background = "#2E3440"
bar_foreground = "#D8DEE9"

Technical Troubleshooting Matrix

Essential File Locations & Directories

~/.config/hypr/hyprland.conf       # Hyprland compositor configuration
~/.config/hypr/hyprlock.conf       # Lock screen configuration
~/.config/hypr/hypridle.conf       # Idle timeout & screensaver settings
~/.config/quickshell/              # Quickshell QML panel configuration
~/.config/ghostty/config           # Ghostty terminal configuration
~/.config/nvim/                    # Neovim Lua configuration (init.lua)
~/.config/tmux/tmux.conf           # Tmux multiplexer configuration
~/.config/rofi/                    # Rofi launcher theme & configuration
~/.config/starship.toml            # Starship prompt configuration
~/.config/omarchy/                 # Omarchy-specific settings & themes
~/.local/bin/                      # User scripts (Omarchy CLI lives here)
~/.local/share/hyprland/           # Hyprland logs and runtime data
/etc/omarchy/                      # System-wide Omarchy configuration

Bundled Software Ecosystem Reference

Terminal & Development

CLI Utilities

GUI Applications

Agent Operational Directive

MANDATORY: When configuring Omarchy systems, always verify the Hyprland compositor version with hyprctl version, check that Wayland session variables are set (echo $XDG_SESSION_TYPE), and use hyprctl reload rather than restarting the compositor to apply configuration changes non-destructively. Always back up configuration files before modifying them: cp ~/.config/hypr/hyprland.conf ~/.config/hypr/hyprland.conf.bak.