omarchy
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseOmarchy Skill
Omarchy 系统管理技能
Manage Omarchy Linux systems - a beautiful, modern, opinionated Arch Linux distribution with Hyprland.
管理Omarchy Linux系统——这是一款基于Hyprland的美观、现代且具有明确设计理念的Arch Linux发行版。
When This Skill MUST Be Used
必须使用此技能的场景
ALWAYS invoke this skill when the user's request involves ANY of these:
- Editing ANY file in (window rules, animations, keybindings, monitors, etc.)
~/.config/hypr/ - 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 command
omarchy-* - 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.
当用户的请求涉及以下任意一项时,务必调用此技能:
- 编辑下的任意文件(窗口规则、动画、快捷键、显示器设置等)
~/.config/hypr/ - 编辑、
~/.config/waybar/、~/.config/walker/下的任意文件~/.config/mako/ - 编辑终端配置(alacritty、kitty、ghostty)
- 编辑下的任意文件
~/.config/omarchy/ - 窗口行为、动画、透明度、模糊效果、间隙、边框
- 层规则、工作区设置、显示/显示器配置
- 主题、壁纸、字体、外观修改
- 任何命令
omarchy-* - 截图、录屏、夜灯、空闲行为、锁屏
如果你打算在此系统上编辑~/.config/下的配置文件,请先停止操作并使用此技能。
Critical Safety Rules
关键安全规则
NEVER modify anything in - but READING is safe and encouraged.
~/.local/share/omarchy/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 scriptsReading is SAFE and useful - do it freely to:
~/.local/share/omarchy/- 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:
- - User configuration (safe to edit)
~/.config/ - - Custom themes (must be real directories)
~/.config/omarchy/themes/<custom-name>/ - - Custom automation hooks
~/.config/omarchy/hooks/
绝对不要修改下的任何内容——但可以安全地读取该目录下的文件,且建议这么做。
~/.local/share/omarchy/该目录包含由git管理的Omarchy源文件,任何修改都会:
- 在下次执行时丢失
omarchy-update - 与上游版本产生冲突
- 破坏系统的更新机制
~/.local/share/omarchy/ # 只读——绝对不要编辑(读取没问题)
├── bin/ # 源脚本(已链接到PATH)
├── config/ # 默认配置模板
├── themes/ # 内置主题
├── default/ # 系统默认设置
├── migrations/ # 更新迁移脚本
└── install/ # 安装脚本读取是安全且有用的——你可以自由执行以下操作:
~/.local/share/omarchy/- 了解omarchy命令的工作原理:
cat $(which omarchy-theme-set) - 在自定义前查看默认配置:
cat ~/.local/share/omarchy/config/waybar/config.jsonc - 查看内置主题文件以便复制进行自定义
- 参考默认Hyprland设置:
cat ~/.local/share/omarchy/default/hypr/*
请始终使用以下安全位置进行操作:
- - 用户配置目录(可安全编辑)
~/.config/ - - 自定义主题目录(必须是真实存在的目录)
~/.config/omarchy/themes/<custom-name>/ - - 自定义自动化钩子目录
~/.config/omarchy/hooks/
System Architecture
系统架构
Omarchy is built on:
| Component | Purpose | Config Location |
|---|---|---|
| Arch Linux | Base OS | |
| Hyprland | Wayland compositor/WM | |
| Waybar | Status bar | |
| Walker | App launcher | |
| Alacritty/Kitty/Ghostty | Terminals | |
| Mako | Notifications | |
| SwayOSD | On-screen display | |
Omarchy基于以下组件构建:
| 组件 | 用途 | 配置位置 |
|---|---|---|
| Arch Linux | 基础操作系统 | |
| Hyprland | Wayland合成器/窗口管理器 | |
| Waybar | 状态栏 | |
| Walker | 应用启动器 | |
| Alacritty/Kitty/Ghostty | 终端模拟器 | |
| Mako | 通知管理器 | |
| SwayOSD | 屏幕显示控件 | |
Command Discovery
命令查找
Omarchy provides ~145 commands following pattern.
omarchy-<category>-<action>bash
undefinedOmarchy提供约145个遵循格式的命令。
omarchy-<category>-<action>bash
undefinedList all omarchy commands
列出所有omarchy命令
compgen -c | grep -E '^omarchy-' | sort -u
compgen -c | grep -E '^omarchy-' | sort -u
Find commands by category
按类别查找命令
compgen -c | grep -E '^omarchy-theme'
compgen -c | grep -E '^omarchy-restart'
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)
undefinedcat $(which omarchy-theme-set)
undefinedCommand Categories
命令类别
| Prefix | Purpose | Example |
|---|---|---|
| Reset config to defaults (backs up first) | |
| Restart a service/app | |
| Toggle feature on/off | |
| Theme management | |
| Install optional software | |
| Launch apps | |
| System commands | |
| Package management | |
| Initial setup tasks | |
| System updates | |
| 前缀 | 用途 | 示例 |
|---|---|---|
| 将配置重置为默认值(会先备份) | |
| 重启服务/应用 | |
| 切换功能的开启/关闭状态 | |
| 主题管理 | |
| 安装可选软件 | |
| 启动应用 | |
| 系统命令 | |
| 包管理 | |
| 初始设置任务 | |
| 系统更新 | |
Configuration Locations
配置文件位置
Hyprland (Window Manager)
Hyprland(窗口管理器)
~/.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 filterKey behaviors:
- Hyprland auto-reloads on config save (no restart needed for most changes)
- Use to force reload
hyprctl reload - Use to reset to defaults
omarchy-refresh-hyprland
~/.config/hypr/
├── hyprland.conf # 主配置文件(会引用其他配置)
├── bindings.conf # 快捷键配置
├── monitors.conf # 显示器配置
├── input.conf # 键盘/鼠标设置
├── looknfeel.conf # 外观设置(间隙、边框、动画)
├── envs.conf # 环境变量
├── autostart.conf # 启动应用设置
├── hypridle.conf # 空闲行为设置(屏幕关闭、锁屏、休眠)
├── hyprlock.conf # 锁屏外观设置
└── hyprsunset.conf # 夜灯/蓝光过滤设置关键特性:
- Hyprland会在配置文件保存后自动重新加载(大多数修改无需重启)
- 使用强制重新加载配置
hyprctl reload - 使用将配置重置为默认值
omarchy-refresh-hyprland
Waybar (Status Bar)
Waybar(状态栏)
~/.config/waybar/
├── config.jsonc # Bar layout and modules (JSONC format)
└── style.css # StylingWaybar does NOT auto-reload. You MUST run after any config changes.
omarchy-restart-waybarCommands: , ,
omarchy-restart-waybaromarchy-refresh-waybaromarchy-toggle-waybar~/.config/waybar/
├── config.jsonc # 状态栏布局和模块(JSONC格式)
└── style.css # 样式文件Waybar不会自动重新加载。修改配置后必须运行才能生效。
omarchy-restart-waybar相关命令: 、、
omarchy-restart-waybaromarchy-refresh-waybaromarchy-toggle-waybarTerminals
终端模拟器
~/.config/alacritty/alacritty.toml
~/.config/kitty/kitty.conf
~/.config/ghostty/configCommand:
omarchy-restart-terminal~/.config/alacritty/alacritty.toml
~/.config/kitty/kitty.conf
~/.config/ghostty/config相关命令:
omarchy-restart-terminalOther Configs
其他配置文件
| App | Location |
|---|---|
| btop | |
| fastfetch | |
| lazygit | |
| starship | |
| git | |
| walker | |
| 应用 | 位置 |
|---|---|
| btop | |
| fastfetch | |
| lazygit | |
| starship | |
| git | |
| walker | |
Safe Customization Patterns
安全自定义模式
Pattern 1: Edit User Config Directly
模式1:直接编辑用户配置文件
For simple changes, edit files in :
~/.config/bash
undefined对于简单修改,直接编辑下的文件:
~/.config/bash
undefined1. Read current config
1. 查看当前配置
cat ~/.config/hypr/bindings.conf
cat ~/.config/hypr/bindings.conf
2. Backup before changes
2. 修改前备份
cp ~/.config/hypr/bindings.conf ~/.config/hypr/bindings.conf.bak.$(date +%s)
cp ~/.config/hypr/bindings.conf ~/.config/hypr/bindings.conf.bak.$(date +%s)
3. Make changes with Edit tool
3. 使用编辑工具进行修改
4. Apply changes
4. 应用修改
- Hyprland: auto-reloads on save (no restart needed)
- Hyprland:保存后自动重新加载(无需重启)
- Waybar: MUST restart with omarchy-restart-waybar
- Waybar:必须运行omarchy-restart-waybar生效
- Walker: MUST restart with omarchy-restart-walker
- Walker:必须运行omarchy-restart-walker生效
- Terminals: MUST restart with omarchy-restart-terminal
- 终端:必须运行omarchy-restart-terminal生效
undefinedundefinedPattern 2: Make a new theme
模式2:创建新主题
- 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"
- 在~/.config/omarchy/themes下创建一个目录。
- 通过~/.local/share/omarchy/themes/catppuccin查看现有主题的结构。
- 从互联网下载匹配的壁纸(多张也可),并放入~/.config/omarchy/themes/[新主题名称]目录下。
- 主题制作完成后,运行omarchy-theme-set "新主题名称"
Pattern 3: Use Hooks for Automation
模式3:使用钩子实现自动化
Create scripts in to run automatically on events:
~/.config/omarchy/hooks/bash
undefined在目录下创建脚本,可在特定事件触发时自动运行:
~/.config/omarchy/hooks/bash
undefinedAvailable hooks (see samples in ~/.config/omarchy/hooks/):
可用钩子(查看~/.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"~/.config/omarchy/hooks/
├── theme-set # 主题切换后运行(会将主题名称作为$1参数传入)
├── font-set # 字体切换后运行
└── post-update # omarchy-update执行后运行
钩子示例(`~/.config/omarchy/hooks/theme-set`):
```bash
#!/bin/bash
THEME_NAME=$1
echo "主题已切换为: $THEME_NAME"Add custom actions here
在此添加自定义操作
undefinedundefinedPattern 4: Reset to Defaults -- ALWAYS SEEK USER CONFIRMATION BEFORE RUNNING
模式4:重置为默认值——运行前务必征得用户确认
When customizations go wrong:
bash
undefined当自定义配置出现问题时:
bash
undefinedReset specific config (creates backup automatically)
重置特定配置(会自动创建备份)
omarchy-refresh-waybar
omarchy-refresh-hyprland
omarchy-refresh-waybar
omarchy-refresh-hyprland
The refresh command:
refresh命令的执行流程:
1. Backs up current config with timestamp
1. 为当前配置创建带时间戳的备份
2. Copies default from ~/.local/share/omarchy/config/
2. 从~/.local/share/omarchy/config/复制默认配置
3. Restarts the component
3. 重启对应组件
undefinedundefinedCommon 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 repobash
omarchy-theme-list # 显示可用主题
omarchy-theme-current # 显示当前主题
omarchy-theme-set <name> # 应用主题(使用"Tokyo Night"而非"tokyo-night")
omarchy-theme-next # 切换到下一个主题
omarchy-theme-bg-next # 切换壁纸
omarchy-theme-install <url> # 从Git仓库安装主题Keybindings
快捷键设置
Edit . Format:
~/.config/hypr/bindings.confbind = SUPER, Return, exec, xdg-terminal-exec
bind = SUPER, Q, killactive
bind = SUPER SHIFT, E, exitView current bindings:
omarchy-menu-keybindings --printIMPORTANT: When re-binding an existing key:
- First check existing bindings:
omarchy-menu-keybindings --print - If the key is already bound, you MUST add an directive BEFORE your new
unbindbind - Inform the user what the key was previously bound to
Example - rebinding SUPER+F (which is bound to fullscreen by default):
undefined编辑。格式如下:
~/.config/hypr/bindings.confbind = SUPER, Return, exec, xdg-terminal-exec
bind = SUPER, Q, killactive
bind = SUPER SHIFT, E, exit查看当前快捷键:
omarchy-menu-keybindings --print重要提示:当重新绑定已有快捷键时:
- 首先查看现有绑定:
omarchy-menu-keybindings --print - 如果该快捷键已被绑定,必须在新的指令前添加
bind指令unbind - 告知用户该快捷键之前的绑定功能
示例 - 重新绑定SUPER+F(默认绑定为全屏功能):
undefinedUnbind existing SUPER+F (was: fullscreen)
解绑现有SUPER+F(原功能:全屏)
unbind = SUPER, F
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."bind = SUPER, F, exec, nautilus
务必告知用户:"注意:SUPER+F之前绑定的是全屏功能。我已添加了解绑指令来覆盖原有设置。"Display/Monitors
显示/显示器设置
Edit . Format:
~/.config/hypr/monitors.confmonitor = eDP-1, 1920x1080@60, 0x0, 1
monitor = HDMI-A-1, 2560x1440@144, 1920x0, 1List monitors:
hyprctl monitors编辑。格式如下:
~/.config/hypr/monitors.confmonitor = eDP-1, 1920x1080@60, 0x0, 1
monitor = HDMI-A-1, 2560x1440@144, 1920x0, 1列出显示器:
hyprctl monitorsWindow 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:
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 or a sourced file. Always verify the current syntax from the wiki first.
~/.config/hypr/hyprland.conf重要提示:Hyprland的窗口规则语法在不同版本中经常变化。
在编写任何窗口规则之前,必须从Hyprland官方Wiki获取最新文档:
不要依赖缓存或记忆中的窗口规则语法。该格式已多次变更,使用过时语法会导致错误或意外行为。
窗口规则需写入或其引用的文件中。务必先从Wiki验证当前语法。
~/.config/hypr/hyprland.confFonts
字体设置
bash
omarchy-font-list # Available fonts
omarchy-font-current # Current font
omarchy-font-set <name> # Change fontbash
omarchy-font-list # 显示可用字体
omarchy-font-current # 显示当前字体
omarchy-font-set <name> # 切换字体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 # RebootIMPORTANT: Always run with flags to avoid interactive sudo prompts that will hang the terminal.
omarchy-debug--no-sudo --printbash
omarchy-update # 完整系统更新
omarchy-version # 显示Omarchy版本
omarchy-debug --no-sudo --print # 获取调试信息(务必使用这些参数)
omarchy-lock-screen # 锁屏
omarchy-cmd-shutdown # 关机
omarchy-cmd-reboot # 重启重要提示: 运行时务必添加参数,以避免出现交互式sudo提示导致终端挂起。
omarchy-debug--no-sudo --printTroubleshooting
故障排除
bash
undefinedbash
undefinedGet debug information (ALWAYS use these flags to avoid interactive prompts)
获取调试信息(务必使用这些参数避免交互式提示)
omarchy-debug --no-sudo --print
omarchy-debug --no-sudo --print
Upload logs for support
上传日志以获取支持
omarchy-upload-log
omarchy-upload-log
Reset specific config to defaults
将特定配置重置为默认值
omarchy-refresh-<app>
omarchy-refresh-<app>
Refresh specific config file
刷新特定配置文件
config-file path is relative to ~/.config/
config-file路径是相对于~/.config/的路径
eg. omarchy-refresh-config hypr/hyprlock.conf will refresh ~/.config/hypr/hyprlock.conf
例如:omarchy-refresh-config hypr/hyprlock.conf会刷新~/.config/hypr/hyprlock.conf
omarchy-refresh-config <config-file>
omarchy-refresh-config <config-file>
Full reinstall of configs (nuclear option)
完全重新安装配置(终极方案)
omarchy-reinstall
undefinedomarchy-reinstall
undefinedDecision Framework
决策框架
When user requests system changes:
- Is it a stock omarchy command? Use it directly
- Is it a config edit? Edit in , never
~/.config/~/.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
当用户请求系统修改时:
- 是否是Omarchy内置命令? 直接使用该命令
- 是否是配置编辑? 在下编辑,绝对不要修改
~/.config/~/.local/share/omarchy/ - 是否是主题自定义? 创建新的自定义主题目录
- 是否是自动化需求? 使用下的钩子
~/.config/omarchy/hooks/ - 是否是安装软件包? 使用
yay - 不确定命令是否存在? 使用搜索
compgen -c | grep omarchy
Development (AI Agents)
开发(AI Agents)
When contributing to Omarchy itself (e.g., fixing bugs, adding features), migrations are used to apply changes to existing installations.
当为Omarchy本身做贡献时(如修复Bug、添加功能),需使用迁移脚本来将变更应用到现有安装系统中。
Creating Migrations
创建迁移脚本
bash
undefinedbash
undefinedALWAYS use --no-edit flag or you will get stuck
务必使用--no-edit参数,否则会陷入编辑界面无法退出
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 tasksomarchy-dev-add-migration --no-edit
该命令会创建一个新的迁移文件,并输出其路径,不会打开编辑器。迁移文件名基于Git提交时间戳生成。
**迁移文件**是位于`~/.local/share/omarchy/migrations/`下的Shell脚本,会在`omarchy-update`时在每个系统上运行一次。可用于:
- 使用新默认值更新用户配置
- 安装新依赖
- 执行一次性设置任务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 if needed, then add
unbindinbind~/.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" -> or edit
omarchy-toggle-nightlight~/.config/hypr/hyprsunset.conf - "Customize the catppuccin theme colors" -> Create by copying from stock, then edit
~/.config/omarchy/themes/catppuccin-custom/ - "Run a script every time I change themes" -> Create
~/.config/omarchy/hooks/theme-set - "Reset waybar to defaults" ->
omarchy-refresh-waybar
- "将我的主题切换为catppuccin" ->
omarchy-theme-set catppuccin - "添加SUPER+E快捷键以打开文件管理器" -> 先查看现有绑定,如有必要添加unbind指令,再在中添加bind指令
~/.config/hypr/bindings.conf - "配置我的外接显示器" -> 编辑
~/.config/hypr/monitors.conf - "缩小窗口间隙" -> 编辑
~/.config/hypr/looknfeel.conf - "设置夜灯在日落时自动开启" -> 或编辑
omarchy-toggle-nightlight~/.config/hypr/hyprsunset.conf - "自定义catppuccin主题的颜色" -> 从内置主题复制到目录后进行编辑
~/.config/omarchy/themes/catppuccin-custom/ - "每次切换主题时运行一个脚本" -> 创建脚本
~/.config/omarchy/hooks/theme-set - "将Waybar重置为默认值" ->
omarchy-refresh-waybar