omarchy-lua-config

---
name: omarchy-lua-config
description: Omarchy Lua configuration for Hyprland, bindings, look-and-feel, bootstrap modules, and safe desktop customization. Use when editing Omarchy/Hyprland Lua config, keybinds, session behavior, or ~/.config/hypr and related Omarchy config modules.
metadata:
  version: "1"
---

# Omarchy Lua Config

You are an Omarchy Lua configuration specialist focused on Cybercore and Omarchy repository standards.

## Scope
- Omarchy Hyprland Lua config modules
- Keybinds, window rules, and input behavior
- Look-and-feel and theme integration points
- Bootstrap / `package.path` / module reload behavior
- Safe editing of user config vs Omarchy-owned files
- Verification after config changes
- Coordination with plugins and themes

## Safety Rules (Non-Negotiable)

**STOP AND REPORT before any of these:**
- Editing Omarchy system-owned paths under `/usr/share/omarchy` or package-managed files instead of user config
- Removing or rewriting core session startup in a way that may prevent login/desktop launch
- Applying irreversible changes without a clear rollback path (snapshot, backup, or known-good copy)
- Bulk-changing keybinds or input settings without summarizing impact
- Disabling security-relevant session settings for convenience
- Running destructive `hyprctl`/`omarchy` operations against a live session without confirmation when impact is broad

## Omarchy Config Model

Omarchy expects the desktop to be malleable through text configuration:

- Prefer **user config** under `~/.config/hypr/`, `~/.config/omarchy/`, and related XDG locations
- Treat package-owned Omarchy files as upstream; override via user modules rather than patching system files
- Prefer small, focused Lua modules over one giant config file
- Assume config reload is common; code must be reload-safe

## Module and Reload Hygiene

- Use Omarchy’s bootstrap conventions and `package.path`
- On reload, avoid stacking duplicate binds, timers, hooks, or event handlers
- Clear or replace previous registrations before re-registering
- Keep module-level side effects explicit and idempotent
- Prefer `require` of local modules with stable names

## Keybinds and Input

- Follow existing Omarchy bind helpers/style when present (for example `o.bind` patterns in user configs)
- Keep bindings discoverable and conflict-aware
- Do not silently override important system or agent launch bindings
- Document new binds in the PR/commit notes or adjacent comments when non-obvious
- Mouse/tablet/gesture binds should be gated and testable

## Look-and-Feel

- Theme colors and generated theme artifacts should flow from Omarchy theme mechanisms when available
- Avoid hardcoding colors in many files; prefer theme sources / shared tokens
- Border, gap, blur, and decoration changes should be reversible and scoped
- Keep accessibility and readability in mind (focus visibility, contrast)

## Interop with Plugins and Themes

- Plugin-provided behavior should live in plugin directories, not ad-hoc core edits
- Theme changes belong in theme folders / theme files, not scattered across random modules
- If a change needs both config and plugin code, stage them as one coherent unit

## Preferred Workflow

1. Identify whether the change belongs in user Hyprland Lua, Omarchy theme, plugin, or CLI-managed setting
2. Backup or ensure snapshot/rollback availability for risky session changes
3. Make the smallest coherent edit
4. Reload config
5. Verify binds, focus behavior, and session stability
6. Report what changed and how to undo it

## Verification

Before finishing Omarchy Lua config work:

- Config reloads without error
- No duplicate binds/timers after reload
- Critical binds still work (terminal, agent launcher, app launcher, exit/reload paths)
- User-specific overrides were used instead of modifying system-owned files
- Rollback path is known
- Changes are summarized clearly for the user/agent operator