Omarchy Skill
Manage Omarchy 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-<category>-<action>.
Find Commands
# 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 <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
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:
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
cat ~/.config/<app>/config
2. Backup Before Changes
cp ~/.config/<app>/config ~/.config/<app>/config.bak.$(date +%s)
3. Make Changes
Use the Edit tool. Preserve existing structure and comments.
4. Apply Changes
# For most apps, use the restart command
omarchy-restart-<app>
# Or reset to defaults (creates backup automatically)
omarchy-refresh-<app>
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
omarchy-theme-list # Show available themes
omarchy-theme-current # Show current theme
omarchy-theme-set <name> # Apply theme
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
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
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
omarchy-font-list # Available fonts
omarchy-font-current # Current font
omarchy-font-set <name> # Change font
Troubleshooting
# Check Omarchy state
omarchy-state
# Debug information
omarchy-debug
# Upload logs for support
omarchy-upload-log
# Reset specific config to defaults
omarchy-refresh-<app>
# 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:
- Identify relevant topic(s) from the index above
- Fetch the page using WebFetch with the full URL:
https://learn.omacom.io<path>
- Extract the answer from the page content
- 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?"
1---2name: omarchy3description: Manage and configure Omarchy Linux systems. Use when user asks about Omarchy, Hyprland, themes, keybindings, system config, or any omarchy-* commands.4metadata:5 source: https://skillmd.com/skills/robzolkos/omarchy6---78# Omarchy Skill910Manage [Omarchy](https://omarchy.org/) Linux systems using natural language.1112## ⛔ NEVER MODIFY CORE FILES1314**DO NOT edit, write, or delete any files in `~/.local/share/omarchy/`**1516This directory contains Omarchy's core system files. User configuration belongs in `~/.config/` instead.1718If you need to change behavior controlled by a file in `~/.local/share/omarchy/`, find or create the corresponding override in `~/.config/`.1920## Discovery2122Omarchy provides ~145 commands following the pattern `omarchy-<category>-<action>`.2324### Find Commands2526```bash27# List all omarchy commands28compgen -c | grep -E '^omarchy-' | sort -u2930# Find commands by category31compgen -c | grep -E '^omarchy-theme'32compgen -c | grep -E '^omarchy-restart'3334# Read a command's source to understand it35cat $(which omarchy-theme-set)36```3738### Command Categories3940| Prefix | Purpose | Example |41|--------|---------|---------|42| `omarchy-refresh-*` | Reset config to Omarchy defaults (backs up first) | `omarchy-refresh-waybar` |43| `omarchy-restart-*` | Restart a service/app | `omarchy-restart-waybar` |44| `omarchy-toggle-*` | Toggle feature on/off | `omarchy-toggle-nightlight` |45| `omarchy-theme-*` | Theme management | `omarchy-theme-set <name>` |46| `omarchy-install-*` | Install optional software | `omarchy-install-docker-dbs` |47| `omarchy-launch-*` | Launch apps | `omarchy-launch-browser` |48| `omarchy-cmd-*` | System commands | `omarchy-cmd-screenshot` |49| `omarchy-pkg-*` | Package management | `omarchy-pkg-install <pkg>` |50| `omarchy-setup-*` | Initial setup tasks | `omarchy-setup-fingerprint` |51| `omarchy-update-*` | System updates | `omarchy-update` |5253## Configuration Locations5455### Hyprland (Window Manager)5657```58~/.config/hypr/59├── hyprland.conf # Main config (sources others)60├── bindings.conf # Keybindings61├── monitors.conf # Display configuration62├── input.conf # Keyboard/mouse settings63├── looknfeel.conf # Appearance (gaps, borders, animations)64├── envs.conf # Environment variables65├── autostart.conf # Startup applications66├── hypridle.conf # Idle behavior (screen off, lock, suspend)67├── hyprlock.conf # Lock screen appearance68└── hyprsunset.conf # Night light / blue light filter69```7071**Restart/Refresh:**72- `omarchy-refresh-hyprland` - Reset to defaults73- Hyprland auto-reloads on config save (no restart needed)74- `omarchy-restart-hypridle` / `omarchy-restart-hyprsunset` for those services7576### Waybar (Status Bar)7778```79~/.config/waybar/80├── config.jsonc # Bar layout and modules (JSONC format)81└── style.css # Styling82```8384**Restart/Refresh:**85- `omarchy-restart-waybar` - Restart waybar86- `omarchy-refresh-waybar` - Reset to defaults87- `omarchy-toggle-waybar` - Show/hide8889### Walker (App Launcher)9091```92~/.config/walker/93└── config.toml # Launcher configuration94```9596**Restart/Refresh:**97- `omarchy-restart-walker`98- `omarchy-refresh-walker`99100### Terminals101102```103~/.config/alacritty/alacritty.toml104~/.config/kitty/kitty.conf105~/.config/ghostty/config106```107108**Restart:**109- `omarchy-restart-terminal`110111### Other Configs112113| App | Location |114|-----|----------|115| btop | `~/.config/btop/btop.conf` |116| fastfetch | `~/.config/fastfetch/config.jsonc` |117| lazygit | `~/.config/lazygit/config.yml` |118| starship | `~/.config/starship.toml` |119| git | `~/.config/git/config` |120121## Omarchy Data122123```124~/.local/share/omarchy/125├── bin/ # All omarchy-* scripts126├── config/ # Default config templates127├── themes/ # Installed themes128└── version # Current version info129```130131## Safe Editing Pattern132133When modifying any Omarchy config:134135### 1. Read Current Config136137```bash138cat ~/.config/<app>/config139```140141### 2. Backup Before Changes142143```bash144cp ~/.config/<app>/config ~/.config/<app>/config.bak.$(date +%s)145```146147### 3. Make Changes148149Use the Edit tool. Preserve existing structure and comments.150151### 4. Apply Changes152153```bash154# For most apps, use the restart command155omarchy-restart-<app>156157# Or reset to defaults (creates backup automatically)158omarchy-refresh-<app>159```160161### 5. Explain What You Did162163After completing changes, include a **Learn More** section to help the user understand what happened:164165```166> **Learn More**167>168> [Explain what file(s) were modified or commands were run]169> [Explain why these changes achieve the user's goal]170> [Explain key config options that were set and what they control]171```172173**Example:**174175> **Learn More**176>177> Modified `~/.config/hypr/looknfeel.conf` to change window gaps.178> The `gaps_in` setting controls space between adjacent windows (set to 5px).179> The `gaps_out` setting controls space between windows and screen edges (set to 10px).180181## Common Tasks182183### Themes184185```bash186omarchy-theme-list # Show available themes187omarchy-theme-current # Show current theme188omarchy-theme-set <name> # Apply theme189omarchy-theme-next # Cycle to next theme190omarchy-theme-bg-next # Cycle wallpaper191omarchy-theme-install <url> # Install from git repo192```193194### Keybindings195196Edit `~/.config/hypr/bindings.conf`. Format:197```198bind = SUPER, Return, exec, xdg-terminal-exec199bind = SUPER, Q, killactive200bind = SUPER SHIFT, E, exit201```202203View current bindings: `omarchy-menu-keybindings`204205### Display/Monitors206207Edit `~/.config/hypr/monitors.conf`. Format:208```209monitor = eDP-1, 1920x1080@60, 0x0, 1210monitor = HDMI-A-1, 2560x1440@144, 1920x0, 1211```212213List monitors: `hyprctl monitors`214215### Screenshots216217- `omarchy-cmd-screenshot` - Interactive screenshot218- `omarchy-cmd-screenrecord` - Toggle screen recording219220### System221222```bash223omarchy-update # Full system update224omarchy-version # Show Omarchy version225omarchy-debug # Debug info for troubleshooting226omarchy-lock-screen # Lock screen227omarchy-cmd-shutdown # Shutdown228omarchy-cmd-reboot # Reboot229```230231## Fonts232233```bash234omarchy-font-list # Available fonts235omarchy-font-current # Current font236omarchy-font-set <name> # Change font237```238239## Troubleshooting240241```bash242# Check Omarchy state243omarchy-state244245# Debug information246omarchy-debug247248# Upload logs for support249omarchy-upload-log250251# Reset specific config to defaults252omarchy-refresh-<app>253254# Full reinstall (nuclear option)255omarchy-reinstall256```257258## Omarchy Manual259260**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.261262### When to Fetch the Manual263264**Always fetch first** when users ask:265- "How do I..." / "What is..." / "Why does..." questions266- Questions about installing/running software (Windows, games, apps)267- Questions about concepts, workflows, or best practices268- Topics where Omarchy may have a specific approach269270### Manual Index271272**Match the user's question to topic(s) below and fetch the page(s) before responding:**273274| Topic | Keywords | URL |275|-------|----------|-----|276| Welcome / Overview | what is omarchy, introduction, about | `/2/the-omarchy-manual/91/welcome-to-omarchy` |277| Getting Started | install, installation, setup, ISO, new user | `/2/the-omarchy-manual/50/getting-started` |278| Navigation | tiling, workspaces, move, resize, focus, window management | `/2/the-omarchy-manual/51/navigation` |279| Themes | theme, appearance, colors, look, style | `/2/the-omarchy-manual/52/themes` |280| Extra Themes | community themes, more themes, additional themes | `/2/the-omarchy-manual/90/extra-themes` |281| Making Themes | create theme, custom theme, theme development | `/2/the-omarchy-manual/92/making-your-own-theme` |282| Hotkeys | keybindings, shortcuts, keyboard, hotkey reference | `/2/the-omarchy-manual/53/hotkeys` |283| PDFs | pdf, forms, documents, xournal | `/2/the-omarchy-manual/54/filling-out-pdfs` |284| Applications | apps, software, included, default apps | `/2/the-omarchy-manual/55/the-applications` |285| Neovim | neovim, nvim, vim, editor | `/2/the-omarchy-manual/56/neovim` |286| Shell Tools | fzf, zoxide, ripgrep, rg, search | `/2/the-omarchy-manual/57/shell-tools` |287| Shell Functions | compress, format, convert, shell utilities | `/2/the-omarchy-manual/58/shell-functions` |288| TUIs | lazygit, lazydocker, btop, terminal ui | `/2/the-omarchy-manual/59/tuis` |289| GUIs | obsidian, pinta, localsend, graphical apps | `/2/the-omarchy-manual/60/guis` |290| Commercial GUIs | 1password, typora, paid apps | `/2/the-omarchy-manual/61/commercial-guis` |291| Development Tools | dev, programming, coding, ide | `/2/the-omarchy-manual/62/development-tools` |292| Web Apps | web app, pwa, browser apps | `/2/the-omarchy-manual/63/web-apps` |293| Configuration | config, customize, settings | `/2/the-omarchy-manual/64/configuration` |294| Dotfiles | dotfiles, .config, config files | `/2/the-omarchy-manual/65/dotfiles` |295| Other Packages | pacman, yay, aur, arch packages | `/2/the-omarchy-manual/66/other-packages` |296| FAQ | faq, questions, common issues | `/2/the-omarchy-manual/67/faq` |297| Updates | update, upgrade, system update | `/2/the-omarchy-manual/68/updates` |298| Gaming | games, steam, retroarch, gaming | `/2/the-omarchy-manual/71/gaming` |299| Troubleshooting | problem, issue, fix, broken, not working | `/2/the-omarchy-manual/88/troubleshooting` |300| Backgrounds | wallpaper, background, custom wallpaper | `/2/the-omarchy-manual/89/backgrounds` |301| Security | encryption, firewall, security, luks | `/2/the-omarchy-manual/93/security` |302| Fonts | font, typeface, typography | `/2/the-omarchy-manual/94/fonts` |303| Prompt | starship, prompt, terminal prompt | `/2/the-omarchy-manual/95/prompt` |304| Manual Installation | manual install, arch install, step by step | `/2/the-omarchy-manual/96/manual-installation` |305| Mac Support | mac, macbook, intel mac, apple | `/2/the-omarchy-manual/97/mac-support` |306| Windows VM | windows, run windows, install windows, vm, virtual machine, microsoft | `/2/the-omarchy-manual/100/windows-vm` |307| System Snapshots | snapshot, backup, restore, timeshift | `/2/the-omarchy-manual/101/system-snapshots` |308| Common Tweaks | tweak, customize, adjust, modify | `/2/the-omarchy-manual/102/common-tweaks` |309| Input Devices | keyboard, mouse, trackpad, touchpad, input | `/2/the-omarchy-manual/78/keyboard-mouse-trackpad` |310| Fingerprint / Fido2 | fingerprint, fido, yubikey, biometric | `/2/the-omarchy-manual/77/fingerprint-fido2-authentication` |311| Monitors | monitor, display, screen, resolution, scaling | `/2/the-omarchy-manual/86/monitors` |312| Running Omarchy | vm, virtualbox, vmware, platforms | `/2/the-omarchy-manual/79/omarchy-on` |313314### Fetching Manual Pages315316When a user asks a general question:3173181. **Identify relevant topic(s)** from the index above3192. **Fetch the page** using WebFetch with the full URL:320 ```321 https://learn.omacom.io<path>322 ```3233. **Extract the answer** from the page content3244. **Summarize** the relevant information for the user325326**Examples:**327- "How do I set up my fingerprint reader?" → Fetch `/2/the-omarchy-manual/77/fingerprint-fido2-authentication`328- "How do I install Windows on Omarchy?" → Fetch `/2/the-omarchy-manual/100/windows-vm`329- "How do I install Steam?" → Fetch `/2/the-omarchy-manual/71/gaming`330331## Example Requests332333- "Change my theme to catppuccin"334- "Add a keybinding for Super+E to open file manager"335- "Configure my external monitor"336- "Make the window gaps smaller"337- "Set up night light to turn on at sunset"338- "Show me what omarchy commands are available for bluetooth"339- "Increase waybar height"340- "Change my terminal font"341- "How do I install Steam?"342- "How do I install Windows on Omarchy?"343- "What keyboard shortcuts are available?"344- "How do I set up my fingerprint reader?"