How omarchy-dev-link Enables Development Against a Local Checkout

omarchy-dev-link redirects the running Omarchy installation to use a local source checkout instead of the packaged copy by updating /etc/omarchy.conf and adding a sudoers fragment that modifies the secure path.

The omarchy repository includes a development workflow that lets contributors modify code and test changes without repeatedly reinstalling the package. The omarchy-dev-link script, located at bin/omarchy-dev-link, automates this by reconfiguring two critical system locations that Omarchy respects for runtime path resolution.

How omarchy-dev-link Configures the Runtime Path

Updating /etc/omarchy.conf

The script writes an export OMARCHY_PATH="<checkout-path>" line to /etc/omarchy.conf (lines 6-8 of the script). This environment variable is the primary mechanism Omarchy uses to locate its runtime tree, which includes bin/, default/, shell/, themes/, and other directories.

Once set, every unprivileged Omarchy command (omarchy …) automatically runs code from the specified checkout rather than the system-packaged version. The default/bash/env-bootstrap file sources /etc/omarchy.conf early in the user's shell environment to ensure this variable is available.

Configuring Sudo Access with /etc/sudoers.d/omarchy-dev-path

Because sudo ignores the caller's $PATH and resolves commands against its own secure_path, the script creates a temporary sudoers fragment that prepends the checkout's bin/ directory to the secure path (lines 9-12 and 95-98). This fragment is validated with visudo -cf before installation (lines 100-103) and then installed with sudo install -Dm440 (line 112).

The result: any sudo omarchy-* command resolves to binaries in $checkout/bin rather than the packaged versions. This ensures both regular and privileged Omarchy components use the same source checkout.

Reboot Requirements and Handling

Changes to /etc/omarchy.conf only take effect after a reboot because many services—including Hyprland, systemd, and the login shell—read OMARCHY_PATH only at startup. The script prompts the user to reboot (lines 17-19) unless the --no-reboot flag is supplied (lines 49-55).

# Link your checkout and prompt for reboot

omarchy dev link ~/omarchy

# Link without reboot prompt (plan to reboot later)

omarchy dev link ~/omarchy --no-reboot

Safety Checks Built Into omarchy-dev-link

The script includes several protective mechanisms:

• Refuses to run under sudo (lines 10-13) — prevents permission conflicts
• Verifies checkout structure (lines 82-86) — checks for expected directories (bin, default, shell) and warns if missing
• Validates sudoers syntax — uses visudo -cf to check the generated fragment before installation

Using omarchy-dev-link in Practice

Linking a Checkout

# From your omarchy repository clone

omarchy dev link ~/omarchy

Verifying the Configuration

# Confirm OMARCHY_PATH points to your checkout

echo "$OMARCHY_PATH"

# → /home/you/omarchy

# Verify sudo resolves omarchy-* from the checkout

sudo which omarchy-launch-terminal

# → /home/you/omarchy/bin/omarchy-launch-terminal

Reverting to Packaged Version

Use the companion script to restore system defaults:

omarchy dev unlink

The bin/omarchy-dev-unlink script removes /etc/sudoers.d/omarchy-dev-path and clears the OMARCHY_PATH entry from /etc/omarchy.conf.

How omarchy-dev-link Fits Into the Development Workflow

According to the Omarchy source code as implemented in basecamp/omarchy, this mechanism enables a tight development loop:

1. Edit code in your local checkout
2. Test changes immediately with omarchy commands
3. Use sudo omarchy-* for privileged operations, which also run from the checkout
4. Reboot when necessary to pick up environment changes

The [docs/file-layout.md](https://github.com/basecamp/omarchy/blob/quattro/docs/file-layout.md) file explicitly documents that /etc/omarchy.conf is written by omarchy-dev-link, confirming this is the officially supported development path.

Summary

• omarchy-dev-link redirects Omarchy to a local checkout by setting OMARCHY_PATH in /etc/omarchy.conf and adding a sudoers fragment for secure_path
• Both unprivileged and privileged commands use the checkout, ensuring consistent testing
• Reboot required for full effect due to early environment loading by services
• Safety checks prevent sudo execution, validate checkout structure, and verify sudoers syntax
• Companion omarchy-dev-unlink script restores packaged behavior

Frequently Asked Questions

What happens if I run omarchy-dev-link with sudo?

The script exits with an error. Lines 10-13 of bin/omarchy-dev-link explicitly check for sudo execution and refuse to run, preventing permission conflicts that could corrupt the configuration.

Why do I need to reboot after running omarchy-dev-link?

Many Omarchy services—Hyprland, systemd units, and the login shell—source /etc/omarchy.conf only once at startup. A reboot ensures all components pick up the new OMARCHY_PATH value. Use --no-reboot to suppress the prompt if you plan to restart later.

How does omarchy-dev-link affect sudo commands differently than regular commands?

Regular commands read OMARCHY_PATH directly from the environment. Sudo commands ignore the caller's $PATH, so the script creates /etc/sudoers.d/omarchy-dev-path to prepend the checkout's bin/ to sudo's secure_path. This ensures sudo omarchy-* resolves to checkout binaries.

What directories must exist in my checkout for omarchy-dev-link to work?

The script verifies that bin, default, and shell directories exist in the specified path (lines 82-86). These are essential Omarchy components; the script warns and may fail if any are missing, protecting against invalid checkout paths.

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