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

> Learn the omarchy-dev-link development workflow to replace Omarchy binaries with live Git checkouts and instantly test source code changes. Streamline your Basecamp Omarchy development.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-28

---

**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](https://github.com/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`](https://github.com/basecamp/omarchy/blob/main//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

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md) (line 157), [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//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`](https://github.com/basecamp/omarchy/blob/main/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.

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main//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:

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main/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:

```bash
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`](https://github.com/basecamp/omarchy/blob/main//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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main//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`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md) documentation confirms this location is automatically cleaned up during the uninstall process or when running `omarchy-dev-unlink`.