Split the end-user omarchy skill into topic guides (#6602)
* Split the end-user omarchy skill into topic guides Move default/omarchy-skill to default/agents/skills/omarchy and break the monolithic SKILL.md into on-demand topic files for Hyprland config, shell plugins, theming, and hooks. Update the skill symlink wiring, relink existing installs through a migration, and correct claims that had drifted from the implementation: plugin hot-reload, terminal reload, menu customization, refresh scopes, theme overlays, background locations, hook timing, and the packaged (not git-managed) system directory. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * Add capture and contributing guides to the omarchy skill Cover screenshots, screen recording, OCR text capture, and LocalSend or Taildrop sharing, plus how to route bug reports, suggestions, and support questions upstream with diagnostics and captures of the problem attached. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * Scope Hyprland reload guidance to the Lua config files hyprsunset.conf and xdph.conf are read by separate processes, so hyprctl neither applies nor validates them. Document restarting hyprsunset after editing its config, including in the night light example. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
David Heinemeier Hansson
co-authored by
Claude Fable 5
Claude Fable 5
parent
018f881840
commit
6ee243cc37
@@ -0,0 +1,294 @@
|
||||
---
|
||||
name: omarchy
|
||||
description: >
|
||||
REQUIRED for end-user customization of Linux desktop, window manager, or system config.
|
||||
Use when editing ~/.config/hypr/, ~/.config/omarchy/,
|
||||
~/.config/alacritty/, ~/.config/foot/, ~/.config/kitty/, or ~/.config/ghostty/.
|
||||
Triggers: Hyprland, window rules, animations, keybindings, monitors, gaps, borders,
|
||||
blur, opacity, omarchy-shell, bar, terminal config, themes, background,
|
||||
night light, idle, lock screen, screenshots, reminders, layer rules, workspace
|
||||
settings, display config, and user-facing omarchy commands. Excludes Omarchy
|
||||
source development through `omarchy dev link` workflows.
|
||||
---
|
||||
|
||||
# Omarchy Skill
|
||||
|
||||
Manage [Omarchy](https://omarchy.org/) Linux systems - a beautiful, modern, opinionated Arch Linux distribution with Hyprland.
|
||||
|
||||
This skill is for end-user customization on installed systems.
|
||||
It is not for contributing to Omarchy source code.
|
||||
|
||||
## When This Skill MUST Be Used
|
||||
|
||||
**ALWAYS invoke this skill for end-user requests involving ANY of these:**
|
||||
|
||||
- Editing ANY file in `~/.config/hypr/` (window rules, animations, keybindings, monitors, etc.)
|
||||
- Editing `~/.config/omarchy/shell.json` (status bar layout, widgets)
|
||||
- Editing terminal configs (alacritty, foot, kitty, ghostty)
|
||||
- Editing ANY file in `~/.config/omarchy/`
|
||||
- Window behavior, animations, opacity, blur, gaps, borders
|
||||
- Layer rules, workspace settings, display/monitor configuration
|
||||
- Themes, backgrounds, fonts, appearance changes
|
||||
- User-facing `omarchy` commands (`omarchy theme ...`, `omarchy refresh ...`, `omarchy restart ...`, etc.)
|
||||
- Screenshots, screen recording, reminders, 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.**
|
||||
|
||||
**Do NOT use this skill for Omarchy development tasks** (editing the Omarchy source tree, creating migrations, or running `omarchy dev ...` workflows).
|
||||
|
||||
## Topic Guides
|
||||
|
||||
Deeper instructions for common areas live next to this file. Read the
|
||||
matching guide before starting:
|
||||
|
||||
- [`hyprland.md`](hyprland.md) - keybindings, monitors, window rules, and other Hyprland config
|
||||
- [`plugins.md`](plugins.md) - the Omarchy shell: bar layout, widgets, plugins, idle behavior
|
||||
- [`theming.md`](theming.md) - themes, backgrounds, and fonts
|
||||
- [`hooks.md`](hooks.md) - automation hooks that run on system events
|
||||
- [`capture.md`](capture.md) - screenshots, screen recordings, OCR text capture, and file sharing
|
||||
- [`contributing.md`](contributing.md) - reporting Omarchy bugs and submitting fixes upstream
|
||||
|
||||
## Critical Safety Rules
|
||||
|
||||
For privileged commands, follow the Privilege Escalation rules below: `sudo` when a terminal is available for the password prompt, `pkexec` when it is not. Do not wrap commands that already manage privilege elevation themselves.
|
||||
|
||||
**For end-user customization tasks, NEVER modify anything in `/usr/share/omarchy/`** - but READING is safe and encouraged.
|
||||
|
||||
This directory is owned by the omarchy package. Any local changes will be
|
||||
overwritten on the next `omarchy update`.
|
||||
|
||||
```
|
||||
/usr/share/omarchy/ # READ-ONLY - NEVER EDIT (reading is OK)
|
||||
├── bin/ # Command source (packaged binaries are on PATH)
|
||||
├── config/ # Default config templates
|
||||
├── themes/ # Stock themes
|
||||
├── default/ # System defaults
|
||||
├── shell/ # Omarchy shell source and defaults
|
||||
├── migrations/ # Update migrations
|
||||
└── install/ # Installation scripts
|
||||
```
|
||||
|
||||
**Reading `/usr/share/omarchy/` is SAFE and useful** - do it freely to:
|
||||
- Understand how omarchy commands work: `omarchy theme set --help` or `cat $(which omarchy-theme-set)`
|
||||
- See default configs before customizing: `cat "$OMARCHY_PATH/config/omarchy/shell.json"`
|
||||
- Check stock theme files to copy for customization
|
||||
- Reference default hyprland settings: `cat /usr/share/omarchy/default/hypr/*`
|
||||
|
||||
**Always use these safe locations instead:**
|
||||
- `~/.config/` - User configuration (safe to edit)
|
||||
- `~/.config/omarchy/themes/<custom-name>/` - Custom themes
|
||||
- `~/.config/omarchy/hooks/` - Custom automation hooks
|
||||
|
||||
If the request is to develop Omarchy itself, this skill is out of scope. Follow repository development instructions instead of this skill.
|
||||
|
||||
## Privilege Escalation
|
||||
|
||||
For an interactive script or command run in a visible terminal, use `sudo` for
|
||||
privileged work. Omarchy may grant passwordless `sudo` access to particular
|
||||
commands, and the terminal is the appropriate place to request a password
|
||||
when one is needed.
|
||||
|
||||
Use `pkexec` only when the caller cannot interact with a terminal or cannot
|
||||
enter a password there, such as a command launched by an agent or a graphical
|
||||
background process. Do not replace `sudo` with `pkexec` merely because a
|
||||
command changes system state.
|
||||
|
||||
## System Architecture
|
||||
|
||||
Omarchy is built on:
|
||||
|
||||
| Component | Purpose | Config Location |
|
||||
|-----------|---------|-----------------|
|
||||
| **Arch Linux** | Base OS | `/etc/`, `~/.config/` |
|
||||
| **Hyprland** | Wayland compositor/WM | `~/.config/hypr/` |
|
||||
| **Omarchy shell** | Status bar + notifications (Quickshell) | `~/.config/omarchy/shell.json` |
|
||||
| **Launcher/menus** | Quickshell menu | `~/.config/omarchy/extensions/omarchy-menu.jsonc` |
|
||||
| **Alacritty/Foot/Kitty/Ghostty** | Terminals | `~/.config/<terminal>/` |
|
||||
| **Omarchy OSD** | On-screen display | Quickshell plugin |
|
||||
|
||||
## Command Discovery
|
||||
|
||||
Omarchy ships a single `omarchy` CLI that dispatches to all `omarchy-*` binaries via `omarchy <group> <action>`. Always prefer this form — it is self-documenting and stable. The underlying `omarchy-*` binaries still exist on `PATH` and remain safe to read for source.
|
||||
|
||||
```bash
|
||||
# List every documented command and its summary (--all includes hidden commands)
|
||||
omarchy commands
|
||||
|
||||
# Show the commands inside a group
|
||||
omarchy theme --help
|
||||
omarchy refresh --help
|
||||
omarchy restart --help
|
||||
|
||||
# Show help for a specific command (does not execute it)
|
||||
omarchy theme set --help
|
||||
|
||||
# Machine-readable listing (binary, route, summary, args, aliases)
|
||||
omarchy commands --json
|
||||
|
||||
# Read a command's source to understand it
|
||||
cat $(which omarchy-theme-set)
|
||||
```
|
||||
|
||||
### Command Groups
|
||||
|
||||
Run `omarchy --help` for the full list. The most common groups:
|
||||
|
||||
| Group | Purpose | Example |
|
||||
|-------|---------|---------|
|
||||
| `omarchy refresh` | Reset config to defaults (backs up first) | `omarchy refresh shell` |
|
||||
| `omarchy restart` | Restart a service/app | `omarchy restart shell` |
|
||||
| `omarchy toggle` | Toggle feature on/off | `omarchy toggle nightlight` |
|
||||
| `omarchy theme` | Theme management | `omarchy theme set <name>` |
|
||||
| `omarchy bar` | Bar layout and widgets | `omarchy bar move omarchy.clock --section right` |
|
||||
| `omarchy plugin` | Manage/clone shell plugins | `omarchy plugin clone omarchy.clock` |
|
||||
| `omarchy hook` | Install automation hooks | `omarchy hook install theme-set <script>` |
|
||||
| `omarchy install` | Install optional software / packages | `omarchy install docker dbs` |
|
||||
| `omarchy launch` | Launch apps | `omarchy launch browser` |
|
||||
| `omarchy capture` | Screenshots and recordings | `omarchy capture screenshot` |
|
||||
| `omarchy reminder` | Desktop notification reminders | `omarchy reminder 15 "Pickup Jack"` |
|
||||
| `omarchy pkg` | Package management | `omarchy pkg add <pkg>` |
|
||||
| `omarchy setup` | Interactive setup wizards | `omarchy setup security fingerprint` |
|
||||
| `omarchy update` | System updates | `omarchy update` |
|
||||
|
||||
## Configuration Locations
|
||||
|
||||
Hyprland config lives in `~/.config/hypr/` — see [`hyprland.md`](hyprland.md).
|
||||
The Omarchy shell (bar, notifications, plugins, idle) is configured in
|
||||
`~/.config/omarchy/shell.json` — see [`plugins.md`](plugins.md).
|
||||
|
||||
### Terminals
|
||||
|
||||
```
|
||||
~/.config/alacritty/alacritty.toml
|
||||
~/.config/foot/foot.ini
|
||||
~/.config/kitty/kitty.conf
|
||||
~/.config/ghostty/config
|
||||
```
|
||||
|
||||
**Command:** `omarchy restart terminal`
|
||||
|
||||
### Other Configs
|
||||
|
||||
| App | Location |
|
||||
|-----|----------|
|
||||
| btop | `~/.config/btop/btop.conf` |
|
||||
| fastfetch | `/etc/fastfetch/config.jsonc` default; `~/.config/fastfetch/config.jsonc` user override |
|
||||
| lazygit | `~/.config/lazygit/config.yml` |
|
||||
| starship | `~/.config/starship.toml` |
|
||||
| git | `~/.config/git/config` |
|
||||
|
||||
## Safe Customization Patterns
|
||||
|
||||
### Edit User Config Directly
|
||||
|
||||
For simple changes, edit files in `~/.config/`:
|
||||
|
||||
```bash
|
||||
# 1. Read current config
|
||||
cat ~/.config/hypr/bindings.lua
|
||||
|
||||
# 2. Backup before changes
|
||||
cp ~/.config/hypr/bindings.lua ~/.config/hypr/bindings.lua.bak.$(date +%s)
|
||||
|
||||
# 3. Make changes with Edit tool
|
||||
|
||||
# 4. Apply changes
|
||||
# - Hyprland: auto-reloads on save, but MUST validate with `hyprctl reload` and `hyprctl configerrors`
|
||||
# - Omarchy shell: shell.json and user plugin code under ~/.config/omarchy/plugins/ hot-reload on save
|
||||
# - Menus/launcher: ~/.config/omarchy/extensions/omarchy-menu.jsonc hot-reloads on save
|
||||
# - Terminals: apply with `omarchy restart terminal` (reloads running terminals; foot picks changes up in new windows)
|
||||
```
|
||||
|
||||
### Reset to Defaults -- ALWAYS SEEK USER CONFIRMATION BEFORE RUNNING
|
||||
|
||||
When customizations go wrong:
|
||||
|
||||
```bash
|
||||
# Reset specific config (creates backup automatically)
|
||||
omarchy refresh shell
|
||||
omarchy refresh hyprland
|
||||
|
||||
# The refresh command:
|
||||
# 1. Backs up current config with timestamp
|
||||
# 2. Copies default from $OMARCHY_PATH/config/
|
||||
# 3. Restarts the component where the refresh needs it (e.g. `refresh shell`)
|
||||
```
|
||||
|
||||
## System Commands
|
||||
|
||||
```bash
|
||||
omarchy update # Full system update
|
||||
omarchy version # Show Omarchy version
|
||||
omarchy debug --no-sudo --print # Debug info (ALWAYS use these flags)
|
||||
omarchy system lock # Lock screen
|
||||
omarchy system shutdown # Shutdown
|
||||
omarchy system 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
|
||||
|
||||
# Reset specific config to defaults
|
||||
omarchy refresh <app>
|
||||
|
||||
# Refresh specific config file
|
||||
# config-file path is relative to ~/.config/
|
||||
# eg. `omarchy refresh config hypr/hyprland.lua` will refresh ~/.config/hypr/hyprland.lua
|
||||
omarchy refresh config <config-file>
|
||||
|
||||
# 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 `/usr/share/omarchy/`
|
||||
3. **Is it a theme customization?** Follow [`theming.md`](theming.md); create a NEW custom theme directory
|
||||
4. **Is it automation?** Follow [`hooks.md`](hooks.md); use `omarchy hook install` and the hook `.d` directories
|
||||
5. **Is it a package install?** Use `omarchy pkg add <pkgs...>` (or `omarchy pkg aur add <pkgs...>` for AUR-only packages)
|
||||
6. **Is it built-in shell/plugin code?** Follow [`plugins.md`](plugins.md); clone it with `omarchy plugin clone`, never edit the packaged copy
|
||||
7. **Unsure if command exists?** Run `omarchy commands` (or `omarchy <group> --help` for one group)
|
||||
|
||||
### Reminder Requests
|
||||
|
||||
When the user asks to set a reminder, use `omarchy reminder <minutes> [message]` directly. Convert natural language durations to minutes and title-case short reminder labels when appropriate.
|
||||
|
||||
```bash
|
||||
omarchy reminder 15 "Pickup Jack"
|
||||
omarchy reminder 60 "Check laundry"
|
||||
omarchy reminder show
|
||||
omarchy reminder clear
|
||||
```
|
||||
|
||||
## Out of Scope
|
||||
|
||||
This skill intentionally does not cover Omarchy source development. Do not use this skill for:
|
||||
- Editing files in `/usr/share/omarchy/` (`bin/`, `config/`, `default/`, `shell/`, `themes/`, `migrations/`, etc.)
|
||||
- Creating or editing migrations
|
||||
- Running `omarchy dev ...` commands
|
||||
|
||||
## 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, call `hl.unbind` if needed, then `o.bind` in `~/.config/hypr/bindings.lua`
|
||||
- "Configure my external monitor" -> Edit `~/.config/hypr/monitors.lua`
|
||||
- "Make the window gaps smaller" -> Edit `~/.config/hypr/looknfeel.lua`
|
||||
- "Turn on night light" -> `omarchy toggle nightlight` (for time-based schedules, edit `~/.config/hypr/hyprsunset.conf` profiles, then `omarchy restart hyprsunset`)
|
||||
- "Set a reminder to pickup jack in 15 minutes" -> `omarchy reminder 15 "Pickup Jack"`
|
||||
- "Show my reminders" -> `omarchy reminder show`
|
||||
- "Clear all reminders" -> `omarchy reminder clear`
|
||||
- "Customize the catppuccin theme colors" -> Overlay: put an edited `colors.toml` in `~/.config/omarchy/themes/catppuccin/`, then re-apply the theme (see `theming.md`)
|
||||
- "Run a script every time I change themes" -> Install it with `omarchy hook install theme-set <script>`
|
||||
- "Change how workspace labels are rendered" -> Clone `omarchy.workspaces`, which switches the bar to `<username>.workspaces`, then edit the clone
|
||||
- "Lock after ten minutes" -> Set `idle.lock` to `600` in `~/.config/omarchy/shell.json`
|
||||
- "Reset shell/bar to defaults" -> `omarchy refresh shell`
|
||||
- "Record my screen" -> `omarchy screenrecord --fullscreen`, then `omarchy screenrecord --stop-recording` (see `capture.md`)
|
||||
- "Report this bug to Omarchy" -> Gather diagnostics and a capture of the problem, then file it (see `contributing.md`)
|
||||
@@ -0,0 +1,60 @@
|
||||
# Capture and Sharing
|
||||
|
||||
Read this before taking screenshots or screen recordings, extracting text from
|
||||
the screen, or sharing files with other machines.
|
||||
|
||||
## Screenshots
|
||||
|
||||
```bash
|
||||
omarchy screenshot # Interactive smart-region flow
|
||||
omarchy capture screenshot region # Select a region
|
||||
omarchy capture screenshot windows # Pick a window
|
||||
omarchy capture screenshot fullscreen save # Full screen, straight to disk (no editor)
|
||||
```
|
||||
|
||||
The first argument picks the mode (`smart|region|windows|fullscreen`), the
|
||||
second what happens with it (`slurp|copy|save`). `save` skips the annotation
|
||||
editor and prints the saved path. Screenshots land in the configured Pictures
|
||||
directory (override with `OMARCHY_SCREENSHOT_DIR`).
|
||||
|
||||
## Screen Recording
|
||||
|
||||
```bash
|
||||
omarchy screenrecord --fullscreen # Start recording the full screen
|
||||
# ...exercise whatever you want on film...
|
||||
omarchy screenrecord --stop-recording # Stop; prints the saved path
|
||||
```
|
||||
|
||||
Optional flags: `--with-desktop-audio`, `--with-microphone-audio`,
|
||||
`--with-webcam` (plus `--webcam-device=` and `--webcam-size=`), and
|
||||
`--resolution=<size>`. Without `--fullscreen` a region picker opens first.
|
||||
Recordings land in the configured Videos directory (override with
|
||||
`OMARCHY_SCREENRECORD_DIR`). Resize a live webcam overlay with
|
||||
`omarchy capture webcam resize <smaller|larger|reset|small|medium|large>`.
|
||||
|
||||
If recording fails to start, rerun with `OMARCHY_SCREENRECORD_DEBUG=true` to
|
||||
collect a log at `/tmp/omarchy-screenrecord.log` worth attaching to a bug
|
||||
report.
|
||||
|
||||
## Text Capture (OCR)
|
||||
|
||||
```bash
|
||||
omarchy capture text # Select a region; extracted text goes to the clipboard
|
||||
```
|
||||
|
||||
## Sharing Files
|
||||
|
||||
```bash
|
||||
omarchy share clipboard # Share the clipboard via LocalSend
|
||||
omarchy share file <path...> # Share files with nearby devices
|
||||
omarchy share folder <path> # Share a folder
|
||||
|
||||
omarchy tailscale send <machine> <file...> # Taildrop to a tailnet machine
|
||||
omarchy tailscale receive [directory] # Save incoming Taildrop files
|
||||
```
|
||||
|
||||
Shrink large captures before sharing them:
|
||||
|
||||
```bash
|
||||
omarchy transcode <input> [format] [resolution] # Re-encode pictures/videos for sharing
|
||||
```
|
||||
@@ -0,0 +1,65 @@
|
||||
# Reporting Issues and Submitting PRs
|
||||
|
||||
Read this when the user wants to report an Omarchy bug, suggest a feature, or
|
||||
contribute a fix upstream.
|
||||
|
||||
Omarchy lives at https://github.com/basecamp/omarchy. Route requests to the
|
||||
right place:
|
||||
|
||||
- **Verified bugs** -> GitHub issues. Issues are for validated bugs only, not
|
||||
support requests.
|
||||
- **Feature ideas and suggestions** ->
|
||||
https://github.com/basecamp/omarchy/discussions/categories/suggestions
|
||||
- **Support and "is this a bug?" questions** -> the Discord community at
|
||||
https://omarchy.org/discord. Start here when the problem isn't clearly a bug
|
||||
in Omarchy itself.
|
||||
|
||||
## Filing a Good Bug Report
|
||||
|
||||
The bug template asks for system details (CPU, GPU, Omarchy version), a
|
||||
description with steps to reproduce, and diagnostics. Gather them:
|
||||
|
||||
```bash
|
||||
omarchy version
|
||||
|
||||
# Generate the diagnostic log (also written to /tmp/omarchy-debug.log)
|
||||
omarchy debug --no-sudo --print
|
||||
|
||||
# Interactive variant: `omarchy debug` offers to upload the log to
|
||||
# logs.omarchy.org (expires after 24h) and prints a shareable URL to
|
||||
# include in the issue.
|
||||
```
|
||||
|
||||
**Capture the problem on screen.** A screenshot or short recording of the bug
|
||||
is often worth more than the description — see [`capture.md`](capture.md) for
|
||||
`omarchy capture screenshot` and `omarchy screenrecord`. Keep recordings short
|
||||
and focused on the misbehavior. GitHub issue attachments are added by
|
||||
drag-and-drop in the web form, so save the capture and hand the user the file
|
||||
path to attach (`gh` cannot upload media).
|
||||
|
||||
For screen-recording failures specifically, rerun with
|
||||
`OMARCHY_SCREENRECORD_DEBUG=true` and attach `/tmp/omarchy-screenrecord.log`.
|
||||
|
||||
File the issue with `gh` when available:
|
||||
|
||||
```bash
|
||||
gh issue create --repo basecamp/omarchy --title "..." --body "..."
|
||||
```
|
||||
|
||||
Include: what happened, what was expected, steps to reproduce, system details,
|
||||
the debug log URL (or attached log), and the capture.
|
||||
|
||||
## Submitting a PR
|
||||
|
||||
Never develop against `/usr/share/omarchy`. Clone a working copy instead:
|
||||
|
||||
```bash
|
||||
gh repo fork basecamp/omarchy --clone
|
||||
cd omarchy
|
||||
```
|
||||
|
||||
Follow the repository's own `AGENTS.md` for style, testing, and commit
|
||||
conventions — it is the authority on contributions. Keep commits atomic, run
|
||||
`./test/all` before pushing, and open the PR with `gh pr create`. A PR that
|
||||
fixes a visual problem should include before/after captures (again, see
|
||||
[`capture.md`](capture.md)).
|
||||
@@ -0,0 +1,28 @@
|
||||
# Automation Hooks
|
||||
|
||||
Read this before setting up scripts that run on system events (theme changes,
|
||||
updates, boot, low battery, etc.).
|
||||
|
||||
Hooks live in `~/.config/omarchy/hooks/<name>.d/` — one directory per event,
|
||||
holding any number of independent scripts. Install with
|
||||
`omarchy hook install <name> <script>` (copies the script in and makes it
|
||||
executable). The runner also executes a flat `~/.config/omarchy/hooks/<name>`
|
||||
file first, if one exists.
|
||||
|
||||
```
|
||||
~/.config/omarchy/hooks/
|
||||
├── battery-low.d/ # Low battery (percentage in $1)
|
||||
├── font-set.d/ # After font change (font name in $1)
|
||||
├── post-boot.d/ # After the desktop starts
|
||||
├── post-update.d/ # During `omarchy update`, after system packages and migrations
|
||||
├── pre-refresh-pacman.d/ # Before `omarchy refresh pacman` re-syncs packages
|
||||
└── theme-set.d/ # After theme change (theme slug in $1)
|
||||
```
|
||||
|
||||
Example hook script:
|
||||
```bash
|
||||
#!/bin/bash
|
||||
THEME_NAME=$1
|
||||
echo "Theme changed to: $THEME_NAME"
|
||||
# Add custom actions here
|
||||
```
|
||||
@@ -0,0 +1,78 @@
|
||||
# Hyprland Configuration
|
||||
|
||||
Read this before changing keybindings, monitors, window rules, or any other
|
||||
Hyprland (window manager) configuration.
|
||||
|
||||
Omarchy configures Hyprland in Lua. User files are loaded after Omarchy's
|
||||
defaults, so overrides go here:
|
||||
|
||||
```
|
||||
~/.config/hypr/
|
||||
├── hyprland.lua # Main config (loads Omarchy defaults, then user files)
|
||||
├── bindings.lua # Keybindings
|
||||
├── monitors.lua # Display configuration
|
||||
├── input.lua # Keyboard/mouse settings
|
||||
├── looknfeel.lua # Appearance (gaps, borders, animations)
|
||||
├── autostart.lua # Startup applications
|
||||
├── hyprsunset.conf # Night light / blue light filter
|
||||
└── xdph.conf # Screen sharing / desktop portal
|
||||
```
|
||||
|
||||
**Key behaviors (the `.lua` files):**
|
||||
- Hyprland auto-reloads on config save (no restart needed for most changes)
|
||||
- Use `hyprctl reload` to force reload
|
||||
- After ANY Hyprland Lua config change, validate with `hyprctl reload` followed by `hyprctl configerrors`
|
||||
- If `hyprctl configerrors` reports errors, address them and rerun validation until clean or until a real blocker is identified
|
||||
- Use `omarchy refresh hyprland` to reset the Lua config files to defaults
|
||||
|
||||
The two `.conf` files are read by separate processes, so `hyprctl` neither
|
||||
applies nor validates them:
|
||||
- `hyprsunset.conf` (night light): apply changes with `omarchy restart hyprsunset`; reset with `omarchy refresh hyprsunset`
|
||||
- `xdph.conf` (screen-sharing portal): applies when the portal restarts, e.g. on next login
|
||||
|
||||
## Keybindings
|
||||
|
||||
Edit `~/.config/hypr/bindings.lua`. Format:
|
||||
```lua
|
||||
o.bind("SUPER + SHIFT + R", "SSH", "alacritty -e ssh your-server")
|
||||
o.bind("SUPER + B", "Browser", { launch = "chromium" }) -- launch wraps with uwsm-app
|
||||
```
|
||||
|
||||
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 call `hl.unbind(...)` BEFORE the new `o.bind(...)`
|
||||
3. Inform the user what the key was previously bound to
|
||||
|
||||
Example - rebinding SUPER+F (which is bound to fullscreen by default):
|
||||
```lua
|
||||
-- Unbind existing SUPER+F (was: fullscreen)
|
||||
hl.unbind("SUPER + F")
|
||||
-- New binding for file manager
|
||||
o.bind("SUPER + F", "File manager", { launch = "nautilus" })
|
||||
```
|
||||
|
||||
Always tell the user: "Note: SUPER+F was previously bound to fullscreen. I've added an unbind to override it."
|
||||
|
||||
## Display/Monitors
|
||||
|
||||
Edit `~/.config/hypr/monitors.lua`. Format:
|
||||
```lua
|
||||
hl.monitor({ output = "eDP-1", mode = "1920x1080@60", position = "0x0", scale = 1 })
|
||||
hl.monitor({ output = "HDMI-A-1", mode = "2560x1440@144", position = "1920x0", scale = 1 })
|
||||
```
|
||||
|
||||
List monitors and supported modes: `hyprctl monitors all`
|
||||
|
||||
## 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://wiki.hypr.land/Configuring/Basics/Window-Rules/
|
||||
|
||||
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.lua` or a required Lua module. Prefer Omarchy's `o.window(match, rules)` helper — see examples in `$OMARCHY_PATH/default/hypr/windows.lua`.
|
||||
@@ -0,0 +1,52 @@
|
||||
# Omarchy Shell: Bar, Plugins, and Idle
|
||||
|
||||
Read this before changing the status bar, notifications, shell plugins,
|
||||
widgets, or idle/lock behavior.
|
||||
|
||||
The bar, notification daemon, settings panel, and assorted overlays all run
|
||||
inside a single long-running Quickshell process (`omarchy-shell`).
|
||||
|
||||
```
|
||||
~/.config/omarchy/shell.json # User overrides: bar, plugins, idle
|
||||
~/.config/omarchy/plugins/<plugin-id>/ # User-owned shell plugins
|
||||
$OMARCHY_PATH/config/omarchy/shell.json # Canonical defaults
|
||||
```
|
||||
|
||||
The shell hot-reloads `shell.json` on save — no restart needed for layout
|
||||
changes. `idle.screensaver` and `idle.lock` are seconds since user idle began.
|
||||
|
||||
**Commands:** `omarchy restart shell`, `omarchy refresh shell`
|
||||
|
||||
## Bar Layout
|
||||
|
||||
Use the `omarchy bar` group to move and manage widgets:
|
||||
|
||||
```bash
|
||||
omarchy bar move omarchy.clock --section right
|
||||
```
|
||||
|
||||
For layout edits beyond what the commands cover, edit the bar configuration
|
||||
in `~/.config/omarchy/shell.json`; it hot-reloads on save.
|
||||
|
||||
## Customizing Built-In Plugins and Widgets
|
||||
|
||||
To customize a built-in bar widget, never edit `$OMARCHY_PATH/shell/plugins/`.
|
||||
Clone it into the user plugin directory instead:
|
||||
|
||||
```bash
|
||||
omarchy plugin clone omarchy.workspaces
|
||||
# Edit ~/.config/omarchy/plugins/<username>.workspaces/; saved changes reload automatically.
|
||||
```
|
||||
|
||||
Cloning switches the bar to the cloned copy (e.g. `<username>.workspaces`),
|
||||
which is yours to edit and survives updates.
|
||||
|
||||
Saving a file anywhere under `~/.config/omarchy/plugins/` reloads plugin code
|
||||
automatically. If a change somehow fails to apply, force a reload with
|
||||
`omarchy-shell shell rescanPlugins`.
|
||||
|
||||
## Idle and Lock
|
||||
|
||||
Set `idle.screensaver` and `idle.lock` in `~/.config/omarchy/shell.json`,
|
||||
in seconds since user idle began. Example: "lock after ten minutes" means
|
||||
setting `idle.lock` to `600`.
|
||||
@@ -0,0 +1,56 @@
|
||||
# Themes, Backgrounds, and Fonts
|
||||
|
||||
Read this before changing themes, backgrounds, fonts, or theme colors.
|
||||
|
||||
## Theme Commands
|
||||
|
||||
```bash
|
||||
omarchy theme list # Show available themes
|
||||
omarchy theme current # Show current theme
|
||||
omarchy theme set <name> # Apply theme ("Tokyo Night" and "tokyo-night" both work)
|
||||
omarchy theme bg next # Cycle background
|
||||
omarchy theme install <url> # Install from git repo
|
||||
```
|
||||
|
||||
## Making a New Theme
|
||||
|
||||
1. Create a directory under `~/.config/omarchy/themes`.
|
||||
2. See how an existing theme is done via `/usr/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>/backgrounds/`.
|
||||
4. When done with the theme, run `omarchy theme set "Name of new theme"`.
|
||||
|
||||
Additional user backgrounds for any theme (stock or custom) go in
|
||||
`~/.config/omarchy/backgrounds/<theme-slug>/`.
|
||||
|
||||
## Customizing a Stock Theme
|
||||
|
||||
Never edit stock themes under `/usr/share/omarchy/themes/` — changes are lost
|
||||
on update. Two safe options:
|
||||
|
||||
**Overlay (preferred for small tweaks):** create a user theme directory with
|
||||
the SAME slug containing only the files you want to change. When the theme is
|
||||
applied, the stock theme is copied first and your files win on top:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.config/omarchy/themes/catppuccin
|
||||
cp /usr/share/omarchy/themes/catppuccin/colors.toml ~/.config/omarchy/themes/catppuccin/
|
||||
# Edit the copied colors.toml, then re-apply:
|
||||
omarchy theme set catppuccin
|
||||
```
|
||||
|
||||
**Fork:** copy the whole stock theme under a new name for a fully independent
|
||||
variant:
|
||||
|
||||
```bash
|
||||
cp -r /usr/share/omarchy/themes/catppuccin ~/.config/omarchy/themes/catppuccin-custom
|
||||
# Edit ~/.config/omarchy/themes/catppuccin-custom/, then:
|
||||
omarchy theme set catppuccin-custom
|
||||
```
|
||||
|
||||
## Fonts
|
||||
|
||||
```bash
|
||||
omarchy font list # Available fonts
|
||||
omarchy font current # Current font
|
||||
omarchy font set <name> # Change font
|
||||
```
|
||||
Reference in New Issue
Block a user