From 055e969a560d505671e04ae53d6b936dbbde9dd3 Mon Sep 17 00:00:00 2001
From: David Heinemeier Hansson <david@hey.com>
Date: Fri, 6 Feb 2026 11:32:03 +0100
Subject: [PATCH] Let's help our agent friends a little to understand the
 Omarchy code base

---
 AGENTS.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..be738a76
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,62 @@
+# Style
+
+- Two spaces for indentation, no tabs
+- Use Bash syntax for conditionals: `[[ -f $file ]]`, not `[ -f "$file" ]`
+
+# Command Naming
+
+All commands start with `omarchy-`. Prefixes indicate purpose:
+
+- `cmd-` - check if commands exist, misc utility commands
+- `pkg-` - package management helpers
+- `hw-` - hardware detection (return exit codes for use in conditionals)
+- `refresh-` - copy default config to user's `~/.config/`
+- `restart-` - restart a component
+- `launch-` - open applications
+- `install-` - install optional software
+- `setup-` - interactive setup wizards
+- `toggle-` - toggle features on/off
+- `theme-` - theme management
+- `update-` - update components
+
+# Helper Commands
+
+Use these instead of raw shell commands:
+
+- `omarchy-cmd-missing` / `omarchy-cmd-present` - check for commands
+- `omarchy-pkg-missing` / `omarchy-pkg-present` - check for packages
+- `omarchy-pkg-add` - install packages (handles both pacman and AUR)
+- `omarchy-hw-asus-rog` - detect ASUS ROG hardware (and similar `hw-*` commands)
+
+# Config Structure
+
+- `config/` - default configs copied to `~/.config/`
+- `default/themed/*.tpl` - templates with `{{ variable }}` placeholders for theme colors
+- `themes/*/colors.toml` - theme color definitions (accent, background, foreground, color0-15)
+
+# Refresh Pattern
+
+To copy a default config to user config with automatic backup:
+
+```bash
+omarchy-refresh-config hypr/hyprlock.conf
+```
+
+This copies `~/.local/share/omarchy/config/hypr/hyprlock.conf` to `~/.config/hypr/hyprlock.conf`.
+
+# Migrations
+
+To create a new migration, run `omarchy-dev-add-migration --no-edit`. This creates a migration file named after the unix timestamp of the last commit.
+
+Migration format:
+- No shebang line
+- Start with an `echo` describing what the migration does
+
+Example:
+```bash
+echo "Disable fingerprint in hyprlock if fingerprint auth is not configured"
+
+if omarchy-cmd-missing fprintd-list || ! fprintd-list "$USER" 2>/dev/null | grep -q "finger"; then
+  sed -i 's/fingerprint:enabled = .*/fingerprint:enabled = false/' ~/.config/hypr/hyprlock.conf
+fi
+```