From d207d505f5eecdf86b5ef4f37debfc280d1af197 Mon Sep 17 00:00:00 2001 From: Ryan Hughes Date: Wed, 7 Jan 2026 11:19:53 -0500 Subject: [PATCH] Add initial omarchy skill for OpenCode (and friends) (#4090) --- bin/omarchy-launch-opencode | 5 - bin/omarchy-theme-set | 2 +- default/omarchy-skill/SKILL.md | 369 +++++++++++++++++++++++++++++ install/config/all.sh | 1 + install/config/omarchy-ai-skill.sh | 3 + migrations/1767478141.sh | 3 + migrations/1767478687.sh | 8 - 7 files changed, 377 insertions(+), 14 deletions(-) delete mode 100755 bin/omarchy-launch-opencode create mode 100644 default/omarchy-skill/SKILL.md create mode 100644 install/config/omarchy-ai-skill.sh create mode 100644 migrations/1767478141.sh diff --git a/bin/omarchy-launch-opencode b/bin/omarchy-launch-opencode deleted file mode 100755 index 3fddd7e6..00000000 --- a/bin/omarchy-launch-opencode +++ /dev/null @@ -1,5 +0,0 @@ -#!/bin/bash - -# Launch opencode in a terminal that has first been placed in ~/Work. - -exec setsid uwsm-app -- xdg-terminal-exec --app-id=org.omarchy.opencode -e bash -c 'cd ~/Work; opencode' diff --git a/bin/omarchy-theme-set b/bin/omarchy-theme-set index 4132d3b8..efcef520 100755 --- a/bin/omarchy-theme-set +++ b/bin/omarchy-theme-set @@ -49,7 +49,7 @@ omarchy-restart-swayosd omarchy-restart-terminal omarchy-restart-hyprctl omarchy-restart-btop -omarchy-restart-opencode +# omarchy-restart-opencode omarchy-restart-mako # Change app-specific themes diff --git a/default/omarchy-skill/SKILL.md b/default/omarchy-skill/SKILL.md new file mode 100644 index 00000000..d8d85607 --- /dev/null +++ b/default/omarchy-skill/SKILL.md @@ -0,0 +1,369 @@ +--- +name: Omarchy +description: > + REQUIRED for ANY changes to Linux desktop, window manager, or system config. + Use when editing ~/.config/hypr/, ~/.config/waybar/, ~/.config/walker/, + ~/.config/alacritty/, ~/.config/kitty/, ~/.config/ghostty/, ~/.config/mako/, + or ~/.config/omarchy/. Triggers: Hyprland, window rules, animations, keybindings, + monitors, gaps, borders, blur, opacity, waybar, walker, terminal config, themes, + wallpaper, night light, idle, lock screen, screenshots, layer rules, workspace + settings, display config, or any omarchy-* commands. +--- + +# Omarchy Skill + +Manage [Omarchy](https://omarchy.org/) Linux systems - a beautiful, modern, opinionated Arch Linux distribution with Hyprland. + +## When This Skill MUST Be Used + +**ALWAYS invoke this skill when the user's request involves 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, 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 `omarchy-*` command +- 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.** + +## Critical Safety Rules + +**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: `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 themes (must be real directories) +- `~/.config/omarchy/hooks/` - Custom automation hooks + +## 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/Kitty/Ghostty** | Terminals | `~/.config//` | +| **Mako** | Notifications | `~/.config/mako/` | +| **SwayOSD** | On-screen display | `~/.config/swayosd/` | + +## Command Discovery + +Omarchy provides ~145 commands following `omarchy--` pattern. + +```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 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 +``` + +**Key behaviors:** +- Hyprland auto-reloads on config save (no restart needed for most changes) +- Use `hyprctl reload` to force reload +- 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/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/`: + +```bash +# 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 (no restart needed) +# - 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: + +```bash +# 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`): +```bash +#!/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: + +```bash +# 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 + +```bash +omarchy-theme-list # Show available themes +omarchy-theme-current # Show current theme +omarchy-theme-set # Apply theme (use "Tokyo Night" not "tokyo-night") +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 --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 `~/.config/hypr/monitors.conf`. Format: +``` +monitor = eDP-1, 1920x1080@60, 0x0, 1 +monitor = HDMI-A-1, 2560x1440@144, 1920x0, 1 +``` + +List monitors: `hyprctl monitors` + +### Window 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: +- https://github.com/hyprwm/hyprland-wiki/blob/main/content/Configuring/Window-Rules.md + +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 `~/.config/hypr/hyprland.conf` or a sourced file. Always verify the current syntax from the wiki first. + +### Fonts + +```bash +omarchy-font-list # Available fonts +omarchy-font-current # Current font +omarchy-font-set # Change font +``` + +### 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 # Reboot +``` + +**IMPORTANT:** Always run `omarchy-debug` with `--no-sudo --print` flags to avoid interactive sudo prompts that will hang the terminal. + +## Troubleshooting + +```bash +# Get debug information (ALWAYS use these flags to avoid interactive prompts) +omarchy-debug --no-sudo --print + +# Upload logs for support +omarchy-upload-log + +# Reset specific config to defaults +omarchy-refresh- + +# Refresh specific config file +# config-file path is relative to ~/.config/ +# eg. omarchy-refresh-config hypr/hyprlock.conf will refresh ~/.config/hypr/hyprlock.conf +omarchy-refresh-config + +# Full reinstall of configs (nuclear option) +omarchy-reinstall +``` + +## Decision Framework + +When user requests system changes: + +1. **Is it a stock omarchy command?** Use it directly +2. **Is it a config edit?** Edit in `~/.config/`, never `~/.local/share/omarchy/` +3. **Is it a theme customization?** Create a NEW custom theme directory +4. **Is it automation?** Use hooks in `~/.config/omarchy/hooks/` +5. **Is it a package install?** Use `yay` +6. **Unsure if command exists?** Search with `compgen -c | grep omarchy` + +## Development (AI Agents) + +When contributing to Omarchy itself (e.g., fixing bugs, adding features), migrations are used to apply changes to existing installations. + +### Creating Migrations + +```bash +# ALWAYS use --no-edit flag or you will get stuck +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 tasks + +## 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 `unbind` if needed, then add `bind` in `~/.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" -> `omarchy-toggle-nightlight` or edit `~/.config/hypr/hyprsunset.conf` +- "Customize the catppuccin theme colors" -> Create `~/.config/omarchy/themes/catppuccin-custom/` by copying from stock, then edit +- "Run a script every time I change themes" -> Create `~/.config/omarchy/hooks/theme-set` +- "Reset waybar to defaults" -> `omarchy-refresh-waybar` diff --git a/install/config/all.sh b/install/config/all.sh index 5ea7f1b1..e40558b5 100644 --- a/install/config/all.sh +++ b/install/config/all.sh @@ -18,6 +18,7 @@ run_logged $OMARCHY_INSTALL/config/walker-elephant.sh run_logged $OMARCHY_INSTALL/config/fast-shutdown.sh run_logged $OMARCHY_INSTALL/config/sudoless-asdcontrol.sh run_logged $OMARCHY_INSTALL/config/input-group.sh +run_logged $OMARCHY_INSTALL/config/omarchy-ai-skill.sh run_logged $OMARCHY_INSTALL/config/hardware/network.sh run_logged $OMARCHY_INSTALL/config/hardware/set-wireless-regdom.sh run_logged $OMARCHY_INSTALL/config/hardware/fix-fkeys.sh diff --git a/install/config/omarchy-ai-skill.sh b/install/config/omarchy-ai-skill.sh new file mode 100644 index 00000000..31f748cf --- /dev/null +++ b/install/config/omarchy-ai-skill.sh @@ -0,0 +1,3 @@ +# Place in ~/.claude/skills since all tools populate from there as well as their own sources +mkdir -p ~/.claude/skills +ln -s $OMARCHY_PATH/default/omarchy-skill ~/.claude/skills/omarchy diff --git a/migrations/1767478141.sh b/migrations/1767478141.sh new file mode 100644 index 00000000..96d25cf8 --- /dev/null +++ b/migrations/1767478141.sh @@ -0,0 +1,3 @@ +echo "Add Omarchy AI skill for assistance tailoring the system" + +source $OMARCHY_PATH/install/config/omarchy-ai-skill.sh diff --git a/migrations/1767478687.sh b/migrations/1767478687.sh index 2a2588ef..573c413c 100644 --- a/migrations/1767478687.sh +++ b/migrations/1767478687.sh @@ -7,11 +7,3 @@ if [[ ! -f ~/.config/opencode/opencode.json ]]; then mkdir -p ~/.config/opencode cp $OMARCHY_PATH/config/opencode/opencode.json ~/.config/opencode/opencode.json fi - -# Add binding if the key is available -BINDINGS_PATH="$HOME/.config/hypr/bindings.conf" -if ! grep -q "SUPER SHIFT CTRL, A" $BINDINGS_PATH; then - sed -i '/SUPER SHIFT ALT, A/a bindd = SUPER SHIFT CTRL, A, opencode, exec, omarchy-launch-opencode' "$BINDINGS_PATH" -else - echo "Add your own binding for opencode using omarchy-launch-opencode in $BINDINGS_PATH" -fi