Develop for Omarchy

1. Choose the right source

• Confirm the application has a stable upstream release, a real project homepage, and a licence that permits redistribution.
• Search the official Omarchy repository and the AUR first so you do not create a duplicate package.
• Prefer the AUR route when a healthy package already exists there; use a local Omarchy package when custom packaging is genuinely needed.
• Verify every release URL, asset name, architecture, version tag, and checksum against the upstream release.

2. Scaffold the Omarchy package

Work in a fork of the official package repository. Each package belongs in pkgbuilds/<package-name>/ and carries Omarchy metadata in .omarchy/package.json.

# Existing AUR package
bin/add-package package-name

# New package maintained in this repository
bin/add-package package-name --local --scaffold

• Use a lowercase, descriptive package name consistent with Arch naming conventions.
• Keep .omarchy/package.json minimal: declare whether the source is aur or local, then add only behavior the package needs.
• If an AUR package needs lasting changes, store focused patches under .omarchy/patches/ rather than editing synced files without a reproducible patch.
• Use a custom upstream hook only when the repository’s declarative GitHub release provider cannot describe the vendor’s releases.

3. Write trustworthy package metadata

• Set accurate pkgver, pkgrel, description, architecture, URL, and licence fields.
• List runtime dependencies in depends and build-only tools in makedepends; do not rely on software that merely happens to be installed on your machine.
• Use provides, conflicts, and replaces only when their exact package-management semantics are required.
• Use cryptographic checksums for downloaded release assets. Never copy a checksum from an untrusted mirror or disable verification just to make a build pass.
• Map every supported architecture to the correct asset, or explicitly limit arch when upstream does not support another architecture.

4. Package files safely

• Install bundled applications under an appropriate system location such as /opt/<app>, with launchers in standard executable paths.
• Keep PKGBUILDs, metadata, desktop entries, and data files non-executable; grant 755 only to actual programs and scripts.
• Avoid setuid, broad write permissions, unnecessary capabilities, and elevated post-install actions. Document any privilege that is truly unavoidable.
• Do not hard-code a username, home directory, local build path, private host, credential, API key, or maintainer-only infrastructure.
• Make uninstalling remove packaged files without deleting user-created data or configuration.

5. Integrate with the desktop

• Provide a valid .desktop launcher with matching executable, icon, categories, and startup behavior.
• Install icons into standard system icon locations and verify they appear in the Omarchy application launcher.
• Launch the app from both a terminal and the application menu under Hyprland; watch for Wayland, portal, tray, notification, and file-picker problems.
• Keep install messages short and limited to user actions that are genuinely required after installation.

6. Test like a new user

• Build from a clean checkout and, when practical, in a clean Arch chroot so undeclared local dependencies cannot hide mistakes.
• Run namcap against the PKGBUILD and built package, then review warnings rather than dismissing them automatically.
• Use the repository’s dry-run option to inspect the build plan before running a real package build.
• Install the resulting package, exercise its main workflows as a normal user, reboot or log in again if integration depends on a new session, then uninstall it.
• Inspect the final package file list, ownership, permissions, dependencies, installed size, and absence of build-machine paths or secrets.
• If multiple architectures are declared, test each one or clearly state which architecture remains unverified.

7. Prepare a useful pull request

• Keep the change focused: package files, required Omarchy metadata, and only the patches or hooks needed to reproduce the result.
• Explain the app, why it belongs in Omarchy, where the source came from, how updates are tracked, and exactly what you tested.
• Include important limitations, architecture gaps, unusual permissions, proprietary licensing, network services, or accounts the app requires.
• Review the complete diff for generated junk, personal information, credentials, local paths, and unrelated edits before pushing.
• Expect maintainer revisions. A strong submission is safe, reproducible, understandable, and easy to refine.

Extra tips that prevent common failures

Authoritative references

This page is a friendly companion, not a replacement for upstream rules.

• Official Omarchy Package Repository — current metadata, scaffolding, build, architecture, and update workflow.
• ArchWiki: Creating packages — PKGBUILD fundamentals and validation.
• ArchWiki: Building in a clean chroot — isolated build testing.