Understanding the omarchy-dev-link Development Workflow in Basecamp's Omarchy

The omarchy-dev-link development workflow enables developers to replace Omarchy's packaged binaries with a live Git checkout, automatically fast-forwarding the source during updates for immediate testing of changes.

The omarchy-dev-link mechanism in the basecamp/omarchy repository creates a seamless live-coding environment. By injecting a local repository checkout into the system's $PATH and Omarchy's internal resolution logic, developers can edit source code, commit changes, and test them immediately without reinstalling packages or restarting sessions.

How omarchy-dev-link Works

The workflow operates through path injection and automatic synchronization. When enabled, the specified checkout directory becomes the authoritative source for Omarchy commands, overriding installed binaries while maintaining security contexts for privileged operations.

Enabling the Development Link

To activate the workflow, run omarchy-dev-link <checkout-path> as your regular user account—never under sudo. This command, located at bin/omarchy-dev-link in the repository, performs two critical configuration changes:

1. Writes the checkout path to /etc/omarchy.conf, prepending it to the system PATH
2. Adds the checkout to sudo's secure_path, ensuring privileged Omarchy commands resolve to the linked version

# Link your local checkout (run as normal user, not sudo)

omarchy-dev-link ~/projects/omarchy

# Verify the configuration

omarchy-dev-status

# Output: dev-link: configured

According to docs/file-layout.md (line 157), /etc/omarchy.conf persists the dev-link configuration and is automatically reset during the uninstall process.

Automatic Fast-Forwarding During Updates

When you run omarchy update, the system first invokes omarchy-update-dev (documented in docs/update-process.md at line 38). This script fetches the upstream remote of your linked checkout and fast-forwards it to the latest commit before executing any system-package upgrades.

This sequencing prevents version conflicts between stale checkout code and new package dependencies. After the fast-forward completes, the updated source is immediately active in your current shell session.

# Edit source, commit, and fast-forward in one update cycle

cd ~/projects/omarchy
git commit -am "Fix widget rendering logic"
omarchy update  # Automatically fast-forwards the checkout first

Path Handling and Resolution

The dev-linked checkout establishes itself as the single source of truth for OMARCHY_PATH. The implementation ensures that both interactive shells and sudo contexts use the development binaries through the dev-link-aware PATH configuration managed in /etc/omarchy.conf.

Managing the Development Link

The workflow includes utilities to inspect and remove the development configuration without manual file editing.

Checking Link Status

The omarchy-dev-status command queries the current configuration state, reporting whether a dev-link is active and which checkout path is currently injected.

Unlinking and Restoring Production Binaries

When you need to return to the stable packaged version, execute omarchy-dev-unlink (source at bin/omarchy-dev-unlink). This utility removes the checkout from secure_path and restores the original PATH order:

# Return to packaged Omarchy binaries

omarchy-dev-unlink

# Verify removal

omarchy-dev-status  # Should indicate no active dev-link

Testing the Workflow

The repository includes automated validation for the dev-link mechanism. The test suite at test/shell.d/dev-link-test.sh exercises the command-line interface using a temporary checkout, validating that:

• The dev-link command correctly writes configuration files
• Binary resolution prefers the linked checkout over system packages
• The unlink command properly restores original paths

Run the test directly when modifying dev-link functionality:

cd /path/to/omarchy
./test/shell.d/dev-link-test.sh

Summary

• omarchy-dev-link injects a local Git checkout into $PATH and secure_path via /etc/omarchy.conf, enabling live development without package reinstallation.
• The bin/omarchy-dev-link script configures the environment as a regular user, while bin/omarchy-dev-unlink reverses these changes.
• During omarchy update, the system runs omarchy-update-dev first to fast-forward the checkout, preventing version skew between source and packages.
• Path resolution uses the dev-link-aware configuration to ensure both user and sudo contexts reference the development binaries.
• Automated testing in test/shell.d/dev-link-test.sh validates the entire workflow.

Frequently Asked Questions

Can I run omarchy-dev-link with sudo privileges?

No, you should never run omarchy-dev-link under sudo. The command is designed to run as your regular user account; it handles privileged path modifications by updating sudo's secure_path configuration separately. Running it with elevated permissions may result in incorrect file ownership or security context errors.

What happens if I commit changes but don't run omarchy update?

The dev-link workflow only fast-forwards your checkout when explicitly triggered by omarchy update. If you commit changes locally but do not run the update command, the running Omarchy session continues using the previous commit state. To see your changes immediately, commit and then run omarchy update, or manually pull the latest changes in your checkout directory.

How does the workflow handle merge conflicts during fast-forwarding?

The omarchy-update-dev script performs a fast-forward only when the history is linear. If your local checkout has diverged from upstream with conflicting changes, the fast-forward will fail and omarchy update will halt before modifying system packages. You must resolve conflicts manually in the checkout directory before proceeding with the update.

Where is the dev-link configuration stored?

Persistent configuration is written to /etc/omarchy.conf by the omarchy-dev-link utility. This file controls the OMARCHY_PATH variable and the dev-link-aware PATH injection. The docs/file-layout.md documentation confirms this location is automatically cleaned up during the uninstall process or when running omarchy-dev-unlink.

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