# Omarchy > Manage and configure Omarchy Linux systems. Use when user asks about Omarchy, Hyprland, themes, keybindings, system config, or any omarchy-* commands. - Skill: `robzolkos/omarchy` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add robzolkos/omarchy` - Raw SKILL.md: https://api.skillmd.com/api/skills/robzolkos/omarchy/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: robzolkos (https://skillmd.com/u/robzolkos) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/robzolkos/omarchy --- # Omarchy Skill Manage [Omarchy](https://omarchy.org/) Linux systems using natural language. ## ⛔ NEVER MODIFY CORE FILES **DO NOT edit, write, or delete any files in `~/.local/share/omarchy/`** This directory contains Omarchy's core system files. User configuration belongs in `~/.config/` instead. If you need to change behavior controlled by a file in `~/.local/share/omarchy/`, find or create the corresponding override in `~/.config/`. ## Discovery Omarchy provides ~145 commands following the pattern `omarchy--`. ### Find Commands ```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 Omarchy 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 ` | | `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 ` | | `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 ``` **Restart/Refresh:** - `omarchy-refresh-hyprland` - Reset to defaults - Hyprland auto-reloads on config save (no restart needed) - `omarchy-restart-hypridle` / `omarchy-restart-hyprsunset` for those services ### Waybar (Status Bar) ``` ~/.config/waybar/ ├── config.jsonc # Bar layout and modules (JSONC format) └── style.css # Styling ``` **Restart/Refresh:** - `omarchy-restart-waybar` - Restart waybar - `omarchy-refresh-waybar` - Reset to defaults - `omarchy-toggle-waybar` - Show/hide ### Walker (App Launcher) ``` ~/.config/walker/ └── config.toml # Launcher configuration ``` **Restart/Refresh:** - `omarchy-restart-walker` - `omarchy-refresh-walker` ### Terminals ``` ~/.config/alacritty/alacritty.toml ~/.config/kitty/kitty.conf ~/.config/ghostty/config ``` **Restart:** - `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` | ## Omarchy Data ``` ~/.local/share/omarchy/ ├── bin/ # All omarchy-* scripts ├── config/ # Default config templates ├── themes/ # Installed themes └── version # Current version info ``` ## Safe Editing Pattern When modifying any Omarchy config: ### 1. Read Current Config ```bash cat ~/.config//config ``` ### 2. Backup Before Changes ```bash cp ~/.config//config ~/.config//config.bak.$(date +%s) ``` ### 3. Make Changes Use the Edit tool. Preserve existing structure and comments. ### 4. Apply Changes ```bash # For most apps, use the restart command omarchy-restart- # Or reset to defaults (creates backup automatically) omarchy-refresh- ``` ### 5. Explain What You Did After completing changes, include a **Learn More** section to help the user understand what happened: ``` > **Learn More** > > [Explain what file(s) were modified or commands were run] > [Explain why these changes achieve the user's goal] > [Explain key config options that were set and what they control] ``` **Example:** > **Learn More** > > Modified `~/.config/hypr/looknfeel.conf` to change window gaps. > The `gaps_in` setting controls space between adjacent windows (set to 5px). > The `gaps_out` setting controls space between windows and screen edges (set to 10px). ## Common Tasks ### Themes ```bash omarchy-theme-list # Show available themes omarchy-theme-current # Show current theme omarchy-theme-set # Apply theme omarchy-theme-next # Cycle to next theme omarchy-theme-bg-next # Cycle wallpaper omarchy-theme-install # 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` ### 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` ### Screenshots - `omarchy-cmd-screenshot` - Interactive screenshot - `omarchy-cmd-screenrecord` - Toggle screen recording ### System ```bash omarchy-update # Full system update omarchy-version # Show Omarchy version omarchy-debug # Debug info for troubleshooting omarchy-lock-screen # Lock screen omarchy-cmd-shutdown # Shutdown omarchy-cmd-reboot # Reboot ``` ## Fonts ```bash omarchy-font-list # Available fonts omarchy-font-current # Current font omarchy-font-set # Change font ``` ## Troubleshooting ```bash # Check Omarchy state omarchy-state # Debug information omarchy-debug # Upload logs for support omarchy-upload-log # Reset specific config to defaults omarchy-refresh- # Full reinstall (nuclear option) omarchy-reinstall ``` ## Omarchy Manual **IMPORTANT:** For general "how do I" questions, ALWAYS fetch the relevant manual page BEFORE answering. The manual at `https://learn.omacom.io` contains Omarchy-specific guidance that may differ from generic Linux advice. ### When to Fetch the Manual **Always fetch first** when users ask: - "How do I..." / "What is..." / "Why does..." questions - Questions about installing/running software (Windows, games, apps) - Questions about concepts, workflows, or best practices - Topics where Omarchy may have a specific approach ### Manual Index **Match the user's question to topic(s) below and fetch the page(s) before responding:** | Topic | Keywords | URL | |-------|----------|-----| | Welcome / Overview | what is omarchy, introduction, about | `/2/the-omarchy-manual/91/welcome-to-omarchy` | | Getting Started | install, installation, setup, ISO, new user | `/2/the-omarchy-manual/50/getting-started` | | Navigation | tiling, workspaces, move, resize, focus, window management | `/2/the-omarchy-manual/51/navigation` | | Themes | theme, appearance, colors, look, style | `/2/the-omarchy-manual/52/themes` | | Extra Themes | community themes, more themes, additional themes | `/2/the-omarchy-manual/90/extra-themes` | | Making Themes | create theme, custom theme, theme development | `/2/the-omarchy-manual/92/making-your-own-theme` | | Hotkeys | keybindings, shortcuts, keyboard, hotkey reference | `/2/the-omarchy-manual/53/hotkeys` | | PDFs | pdf, forms, documents, xournal | `/2/the-omarchy-manual/54/filling-out-pdfs` | | Applications | apps, software, included, default apps | `/2/the-omarchy-manual/55/the-applications` | | Neovim | neovim, nvim, vim, editor | `/2/the-omarchy-manual/56/neovim` | | Shell Tools | fzf, zoxide, ripgrep, rg, search | `/2/the-omarchy-manual/57/shell-tools` | | Shell Functions | compress, format, convert, shell utilities | `/2/the-omarchy-manual/58/shell-functions` | | TUIs | lazygit, lazydocker, btop, terminal ui | `/2/the-omarchy-manual/59/tuis` | | GUIs | obsidian, pinta, localsend, graphical apps | `/2/the-omarchy-manual/60/guis` | | Commercial GUIs | 1password, typora, paid apps | `/2/the-omarchy-manual/61/commercial-guis` | | Development Tools | dev, programming, coding, ide | `/2/the-omarchy-manual/62/development-tools` | | Web Apps | web app, pwa, browser apps | `/2/the-omarchy-manual/63/web-apps` | | Configuration | config, customize, settings | `/2/the-omarchy-manual/64/configuration` | | Dotfiles | dotfiles, .config, config files | `/2/the-omarchy-manual/65/dotfiles` | | Other Packages | pacman, yay, aur, arch packages | `/2/the-omarchy-manual/66/other-packages` | | FAQ | faq, questions, common issues | `/2/the-omarchy-manual/67/faq` | | Updates | update, upgrade, system update | `/2/the-omarchy-manual/68/updates` | | Gaming | games, steam, retroarch, gaming | `/2/the-omarchy-manual/71/gaming` | | Troubleshooting | problem, issue, fix, broken, not working | `/2/the-omarchy-manual/88/troubleshooting` | | Backgrounds | wallpaper, background, custom wallpaper | `/2/the-omarchy-manual/89/backgrounds` | | Security | encryption, firewall, security, luks | `/2/the-omarchy-manual/93/security` | | Fonts | font, typeface, typography | `/2/the-omarchy-manual/94/fonts` | | Prompt | starship, prompt, terminal prompt | `/2/the-omarchy-manual/95/prompt` | | Manual Installation | manual install, arch install, step by step | `/2/the-omarchy-manual/96/manual-installation` | | Mac Support | mac, macbook, intel mac, apple | `/2/the-omarchy-manual/97/mac-support` | | Windows VM | windows, run windows, install windows, vm, virtual machine, microsoft | `/2/the-omarchy-manual/100/windows-vm` | | System Snapshots | snapshot, backup, restore, timeshift | `/2/the-omarchy-manual/101/system-snapshots` | | Common Tweaks | tweak, customize, adjust, modify | `/2/the-omarchy-manual/102/common-tweaks` | | Input Devices | keyboard, mouse, trackpad, touchpad, input | `/2/the-omarchy-manual/78/keyboard-mouse-trackpad` | | Fingerprint / Fido2 | fingerprint, fido, yubikey, biometric | `/2/the-omarchy-manual/77/fingerprint-fido2-authentication` | | Monitors | monitor, display, screen, resolution, scaling | `/2/the-omarchy-manual/86/monitors` | | Running Omarchy | vm, virtualbox, vmware, platforms | `/2/the-omarchy-manual/79/omarchy-on` | ### Fetching Manual Pages When a user asks a general question: 1. **Identify relevant topic(s)** from the index above 2. **Fetch the page** using WebFetch with the full URL: ``` https://learn.omacom.io ``` 3. **Extract the answer** from the page content 4. **Summarize** the relevant information for the user **Examples:** - "How do I set up my fingerprint reader?" → Fetch `/2/the-omarchy-manual/77/fingerprint-fido2-authentication` - "How do I install Windows on Omarchy?" → Fetch `/2/the-omarchy-manual/100/windows-vm` - "How do I install Steam?" → Fetch `/2/the-omarchy-manual/71/gaming` ## Example Requests - "Change my theme to catppuccin" - "Add a keybinding for Super+E to open file manager" - "Configure my external monitor" - "Make the window gaps smaller" - "Set up night light to turn on at sunset" - "Show me what omarchy commands are available for bluetooth" - "Increase waybar height" - "Change my terminal font" - "How do I install Steam?" - "How do I install Windows on Omarchy?" - "What keyboard shortcuts are available?" - "How do I set up my fingerprint reader?"