What Is Dev-Link Mode in Omarchy? A Complete Development Workflow Guide

Dev-link mode redirects the Omarchy runtime to a local source checkout by writing OMARCHY_PATH to /etc/omarchy.conf and modifying sudo's secure_path, allowing developers to test changes instantly without reinstalling the package.

Omarchy is an open-source agent orchestration framework maintained by omacom/omarchy. Dev-link mode in Omarchy provides a streamlined mechanism to develop against a local Git checkout rather than the system-installed package, ensuring that contributors can iterate on core functionality and skills without disrupting the stable installation.

How Dev-Link Mode Works in Omarchy

Writing System-Wide Configuration

When you execute omarchy dev link <path-to-checkout>, the script located at bin/omarchy-dev-link creates /etc/omarchy.conf containing export OMARCHY_PATH="<checkout-path>" (see lines 81–84 and 10–13). This environment variable persists across reboots, ensuring all future processes resolve the Omarchy runtime against your local checkout rather than the default /usr/share/omarchy installation.

Adjusting Sudo Secure Path

The tool generates a temporary sudoers file that prepends <checkout>/bin to the system's secure_path, installing it as /etc/sudoers.d/omarchy-dev-path (lines 23–30, 98–102, and 15–16). This ensures that commands executed via sudo immediately resolve to the checkout's binaries, keeping root-level operations synchronized with your development tree.

Validation and Safety Checks

Before installing the sudoers override, the script validates the file using visudo -cf (lines 104–107). This prevents syntax errors that could lock users out of sudo privileges, ensuring the Omarchy dev-link mode remains safe for system-level development.

Reboot Requirements

Because Hyprland, systemd, login shells, and application launchers read $OMARCHY_PATH only during initialization, the command prompts for a system reboot unless you supply the --no-reboot flag (lines 21–23). A reboot guarantees that all runtime layers pick up the new path and skill symlinks resolve correctly.

Using Dev-Link Mode for Local Development

To activate development mode against a local repository:

# Link a local checkout and prompt for reboot

omarchy dev link ~/omarchy

# Link without rebooting (useful in automation scripts)

omarchy dev link ~/omarchy --no-reboot

# Revert to the packaged installation

omarchy dev unlink

The omarchy dev unlink command, implemented in bin/omarchy-dev-unlink, restores the default configuration by resetting OMARCHY_PATH to /usr/share/omarchy in /etc/omarchy.conf and removing /etc/sudoers.d/omarchy-dev-path (lines 50–58).

Symlink-Based Skill Integration

According to the file-layout documentation, dev-link mode in Omarchy leverages symlink-based skill linking. Any skill directory under $OMARCHY_PATH/default/agents/skills/ is symlinked into the user's ~/.agents/skills/ hierarchy (see docs/file-layout.md, line 211). Because these symlinks resolve against $OMARCHY_PATH, changing the variable via dev-link instantly retargets all skill-related tooling without requiring package rebuilds or reinstalls.

Summary

• Dev-link mode redirects the runtime by setting OMARCHY_PATH in /etc/omarchy.conf and modifying sudo's secure_path via /etc/sudoers.d/omarchy-dev-path.
• The omarchy dev link command validates sudoers syntax with visudo -cf before installation to prevent system lockouts.
• A reboot is required for Hyprland, systemd, and shell environments to recognize the new path unless using --no-reboot.
• Skills remain functional through symlinks in ~/.agents/skills/ that point to $OMARCHY_PATH, making development changes immediately available.
• Use omarchy dev unlink to restore the packaged installation from /usr/share/omarchy.

Frequently Asked Questions

What files does Omarchy dev-link mode modify on my system?

Dev-link mode creates two files: /etc/omarchy.conf containing the OMARCHY_PATH export, and /etc/sudoers.d/omarchy-dev-path adjusting sudo's secure_path. It does not touch fixed-location resources like files in /etc/, /usr/lib/systemd/, or /usr/share/plymouth, which remain unchanged according to lines 34–38 of bin/omarchy-dev-link.

Why does dev-link mode require a reboot in Omarchy?

Most system layers including Hyprland, systemd, login shells, and application launchers read the OMARCHY_PATH environment variable only during initialization. While the sudoers adjustment takes effect immediately, a full reboot ensures all user-space components resolve skills and binaries from the new checkout path, as noted in lines 21–23 of the implementation.

How do I safely exit dev-link mode and return to the stable package?

Run omarchy dev unlink to automatically rewrite /etc/omarchy.conf to point back to /usr/share/omarchy and remove the sudoers drop-in file. The command optionally prompts for a reboot to ensure the system fully reverts to the packaged installation state (lines 50–58 of bin/omarchy-dev-unlink).

Can I use dev-link mode for testing package builds?

No, dev-link mode is specifically for runtime redirection against a source tree. To test modifications to fixed paths like systemd units or Plymouth themes, use omarchy dev pkg-test instead, which rebuilds and installs the package properly rather than symlinking the runtime directory.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}