omarchycn/AGENTS.md

Task Guides

Deeper instructions for specific kinds of work live in agents/skills/. Read the matching guide before starting:

• agents/skills/command-metadata.md - adding or changing commands in bin/
• agents/skills/install-scripts.md - working under install/ or on system/user setup commands
• agents/skills/shell-dev.md - editing the Quickshell desktop under shell/
• agents/skills/icon-font.md - adding branded glyphs to default/fonts/omarchy/omarchy.ttf
• agents/skills/acceptance-tests.md - writing or running graphical acceptance tests under test/acceptance.d/
• agents/skills/visual-verification.md - verifying any change with a visual effect in the running UI
• agents/skills/migrations.md - creating or changing migrations under migrations/

OmarchyCN Layer

This fork carries the OmarchyCN China-integration layer on top of upstream basecamp/omarchy:

• bin/omarchycn routes to omarchy cn <command>; all cn commands are bin/omarchy-cn-* and follow the upstream bin conventions (metadata, helpers, $OMARCHY_PATH — bootstrap exceptions: the overlay installer resolves its own checkout, and omarchy-cn-convert / omarchy-cn-revert are curl-able standalone scripts that default OMARCHY_PATH because they run before/while the cn tree exists)
• Convert/revert: omarchy-cn-convert turns a vanilla package-based Omarchy into OmarchyCN (registry key + [omarchycn] repo, --ask=4 package swap to the cn-built omarchy-dev/omarchy-settings-dev published by packages/publish-cn-packages.sh, [omarchy] mirror line, zh_CN locale, fcitx5 seeding, plymouth rebrand) recording pre-state in /var/lib/omarchycn/convert-state; omarchy-cn-revert restores that state; checkout installs are refused toward the overlay
• cn/ holds the data layer: mirrors.json, dev-mirrors.json, apps.json, registry/ (AI providers/harnesses/compatibility), fcitx5/, fontconfig/, keys/, lib/ (sourced helpers), release (cn release number)
• cn migrations live in cn/migrations/*.sh, run by omarchy-cn-update with per-file completion markers under ~/.local/state/omarchycn/
• Packaging: packages/omarchy-pkgs-cn.patch must be applied to the sibling omarchy-pkgs checkout so omarchy-dev ships cn/; keyring in packages/omarchycn-keyring/
• Upstream repo mirror: packages/sync-omarchy-repo.sh + .gitea/workflows/pkg-repo-sync.yml mirror the upstream [omarchy] stable channel into the Gitea Arch registry every 6h; pacman-stable.conf lists the mirror first (upstream fallback), clients must trust the registry key (install import + cn migration), omarchycn doctor mirror --fix re-heals the line; see docs/pacman-repo.md
• ISO: packages/omarchy-iso-cn.patch must be applied to the sibling omarchy-iso checkout — Chinese installer (cage+foot graphical console with English VT fallback) and live-env packages
• Release process: docs/release-checklist.md; signing: docs/release-signing.md; pacman repo: docs/pacman-repo.md
• Site: site/ is the omarchycn.zacharyzhang.com landing page (Vite 8 vanilla + GSAP + self-hosted Fusion Pixel + reicon, kami palette on a 12-col grid); deploy with npx wrangler deploy from site/, rendered-state checks via node shots.mjs against a preview or the live URL
• Chinese-first defaults: OmarchyCN ships Simplified Chinese as the default UX. User-visible strings in default/omarchy/omarchy-menu.jsonc (all labels), default/hypr/bindings/*.lua (bind descriptions, including the generated workspace/group/panel loops), bin/omarchy-menu-keybindings (its merge list and priority patterns must match the shipped Chinese descriptions), bin/omarchy-update-confirm, and install/user/first-run/* notifications are Chinese with brand names kept in English; menu search stays reachable in English through leaf ids. When syncing upstream, translate new strings in these files and resolve string conflicts toward our Chinese text.
• Default set changes vs upstream: install/omarchy-base.packages adds fcitx5-rime/chinese-addons/configtool and drops aether/libreoffice-fresh/obs-studio; the Basecamp/Discord/HEY/Google/WhatsApp/X launchers, their webapp keybindings, the whatsapp-slim extension, and the HEY mailto handler are removed (preinstall add/remove lists, launcher.hides, chromium flags, and mimeapps stay in sync); install/user/cn-chinese.sh seeds IME/font config on zh_CN systems
• AI: cn/registry/ drives providers (DeepSeek/Kimi/Z.AI/MiniMax/Ollama-local) with zero-code adapters; Ollama uses a fixed static_token and runtime-listed models (models_dynamic); omarchy-default-agent also accepts kimi (official installer script, not mise), deepcode, dim, and dsh (mise npm); the Default Agent menu carries them plus an AI Hub combo entry
• Upstream sync: .gitea/workflows/upstream-sync.yml opens a PR per upstream change; keep upstream file edits minimal and inventoried (currently: one GROUP_DESCRIPTIONS[cn] line in bin/omarchy, the localized menu/bindings/update/first-run surfaces above, the western-app removals above, the cn agent roster in bin/omarchy-default-agent / bin/omarchy-agent (kimi/deepcode/dim/dsh), the [omarchy] mirror line in default/pacman/pacman-stable.conf, the registry-key import in install/post-install/pacman.sh, a rewritten README.md (known recurring sync conflict, resolve toward ours), AGENTS.md additions, and two .gitignore lines)
• cn tests: test/shell.d/omarchycn-test.sh, test/shell.d/omarchycn-ai-test.sh; localized UI expectations live in the upstream suites (menu, keybindings-menu, hyprland-default-config, binding-conflicts, clock, screenrecording, update-disk-space)

Documentation Layout

Three documentation trees, split by genre and audience:

• agents/skills/ - task procedure ("do this when doing X"), for anyone working on the codebase
• docs/ - reference on how the system is shaped (file layout, update pipeline, theming, shell architecture), for anyone working on the codebase; skills link here for depth
• manual/ - end-user documentation for using Omarchy, published; never codebase internals. Chinese user manual for the cn layer lives in manual/zh-cn/

Style

• In markdown documents (plans/, docs/, manual/), write full lines — no hard wrapping at 80 columns; break only at structural boundaries like headings and list items
• Two spaces for indentation, no tabs
• Use bash 5 conditionals: use [[ ]] for string/file tests and (( )) for numeric tests
• In [[ ]], don't quote variables, but do quote string literals when comparing values (e.g., [[ $branch == "dev" ]])
• Prefer (( )) over numeric operators inside [[ ]] (e.g., (( count < 50 )), not [[ $count -lt 50 ]])
• Prefer a full if/else conditional for simple two-path control flow; don't rely on exec or exit in one branch to make following statements unreachable
• For strings/paths with spaces, quote them instead of escaping spaces with \ (e.g., "$APP_DIR/Disk Usage.desktop", not $APP_DIR/Disk\ Usage.desktop)
• Shebangs must use #!/bin/bash consistently (never #!/usr/bin/env bash)
• Scripts under install/ and migrations/ may be sourced and intentionally omit shebangs

Command Naming

All commands start with omarchy-. Prefixes indicate purpose.

The authoritative list of user-facing command groups lives in bin/omarchy in GROUP_DESCRIPTIONS. Keep GROUP_DESCRIPTIONS updated when adding a new command prefix users are meant to browse to.

A group whose commands are all # omarchy:hidden=true gets no entry. That table drives the top-level group listing on its own, so an entry there advertises the group even when every command in it is hidden. apply- and provision- are deliberately absent for that reason; both still route, and omarchy <group> still prints a group header without one.

Common prefixes include:

• cmd- - check if commands exist, misc utility commands
• capture- - screenshots, screen recordings, and other capture tools
• 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

Do not maintain a second exhaustive prefix list here. Consult GROUP_DESCRIPTIONS when selecting or checking a command group so this guidance does not drift from the router.

Runtime Environment

• $OMARCHY_PATH is set at the top level by the uwsm session environment and is always available to Omarchy runtime code.
• Commands in bin/ and Quickshell QML should rely on $OMARCHY_PATH / Quickshell.env("OMARCHY_PATH"); do not derive fallback paths from HOME, Quickshell.shellDir, or re-export/default OMARCHY_PATH manually.

Privileged Commands

• Follow the "Privilege Escalation" section of default/agents/skills/omarchy/SKILL.md. It draws the sudo/pkexec line by whether the caller has a terminal to enter a password in, and the repo's own scripts follow it.

Git

• Commits should be atomic: include only one coherent change or fix, and do not mix unrelated work.
• Commit messages should be succinct and describe the change being made.

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 (don't use these if you can just use omarchy-pkg-add/omarchy-pkg-drop)
• omarchy-pkg-add - install packages (handles both pacman and AUR)
• omarchy-pkg-drop - remove packages; use this instead of raw pacman -R*
• omarchy-notification-send - send desktop notifications; do not call notify-send directly
• omarchy-hw-asus-rog - detect ASUS ROG hardware (and similar hw-* commands)

Commands installed by Omarchy's default package set are runtime invariants. Invoke them directly; do not add defensive omarchy-cmd-present / omarchy-cmd-missing checks around them. Use command-presence helpers only for genuinely optional dependencies or code that can run before the default package set is installed.

Exceptions are allowed for migration and package-helper scripts where the helper may not be available yet, where the helper itself is being implemented, or where direct package-manager behavior is required.

Menu

• The menu definition lives in default/omarchy/omarchy-menu.jsonc; docs/menu.md covers the schema, guards, and providers.
• Do not add aliases to new menu entries. Aliases are reserved for established alternate names users already type, kept for compatibility.

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, red/green/yellow/blue/magenta/cyan and bright_* variants)

Tests

Run focused automated tests for the area you changed; docs/testing.md covers how the suites are shaped. Current test entry points:

• ./test/all - aggregate runner for CLI and shell tests; it intentionally does not run graphical acceptance tests
• ./test/cli - CLI routing, command metadata, theme helpers, and safe dispatch coverage
• ./test/shell - all Omarchy shell tests under test/shell.d/

New Omarchy shell tests should live in test/shell.d/*-test.sh so ./test/shell picks them up automatically. Source test/shell.d/base-test.sh for shared root-path discovery, assertions, and Node test helpers.

The graphical acceptance suite runs in a disposable VM, not in the active development session; see agents/skills/acceptance-tests.md.

Visual changes must be verified in the running UI in addition to automated tests; follow agents/skills/visual-verification.md.

Refresh Pattern

To copy a default config to user config with automatic backup:

omarchy-refresh-config hypr/hyprland.lua

This copies $OMARCHY_PATH/config/hypr/hyprland.lua to ~/.config/hypr/hyprland.lua. The argument is interpolated into both paths and only checked with [[ -e ]], so pass a plain relative path: a name containing .. resolves and copies, landing outside ~/.config rather than being rejected.