How to Set Up a Development Environment for Omarchy: Complete Developer Guide

Omarchy provides a dedicated dev channel that links your running system to a local Git checkout, enabling live updates and testing without rebuilding the OS image.

Setting up a development environment for Omarchy requires switching from the stable release channel to the dev channel, which routes all omarchy-* commands to a local clone of the source tree. This workflow, implemented in the basecamp/omarchy repository, leverages the Mise version manager and Docker to provide a full-stack development stack. By following the official file layout conventions documented in docs/file-layout.md, you can edit source code and test changes immediately without repackaging the operating system.

Install a Fresh Omarchy System

Before configuring the development environment, you must have a working Omarchy installation. Follow the official installation guide in [README.md](https://github.com/basecamp/omarchy/blob/quattro/README.md) to install the base system.

Once installed, verify that the standard Omarchy menu functions by pressing Super + Space to open the launcher.

Install Development Tools and Runtimes

Omarchy bundles a complete development stack managed by Mise. To install the runtimes:

1. Open the Omarchy menu (Super + Space) → Install > Development.
2. This single action installs Node.js, Bun, Deno, Go, Rust, Python, Java, Elixir, .NET, OCaml, Zig, Clojure, Scala, and Docker tooling.
3. Verify Mise is pre-installed by running:

mise --version

The Development tools configuration is documented in [manual/18-development-tools.md](https://github.com/basecamp/omarchy/blob/quattro/manual/18-development-tools.md), which details how the system manages multiple language runties through the Mise shim.

Switch to the Dev Channel and Link Your Repository

The dev channel redirects all Omarchy commands to use a local Git checkout instead of packaged binaries. This is the core mechanism for developing on the system itself.

Switch to the dev channel:

omarchy channel-set dev

Clone the Omarchy repository to your home directory:

git clone https://github.com/basecamp/omarchy.git ~/omarchy

Link the checkout to the running system using the omarchy dev link command:

omarchy dev link ~/omarchy

This command creates /etc/omarchy.conf and a sudoers drop-in file that ensures every omarchy-* command invoked on the system uses the live source code from ~/omarchy rather than the packaged version. The implementation details are documented in [docs/file-layout.md](https://github.com/basecamp/omarchy/blob/quattro/docs/file-layout.md) and the entry point logic resides in bin/omarchy.

Provision Your User Environment

After linking the repository, initialize your user environment to create necessary directories and symlinks:

omarchy provision-user --first-install

This command (defined in [install/user/all.sh](https://github.com/basecamp/omarchy/blob/quattro/install/user/all.sh)) performs the following actions:

• Initializes per-user XDG directories.
• Creates symlinks for skill plugins.
• Generates migration markers for tracking state changes.

You only need to run this once per user account when first setting up the development environment.

Running Tests and Development Sessions

With the dev channel active, you can start a hot-reloading development session:

omarchy dev layout

This launches a Quickshell layout that automatically reloads as you modify source files. For database-dependent development, use the Omarchy menu (Super + Space) → Install > Development to spawn Docker database containers.

To verify your changes against the test suite:

cd ~/omarchy
./test/all

The master test runner executes suites from ./test/shell, ./test/cli, and migration tests as documented in [docs/testing.md](https://github.com/basecamp/omarchy/blob/quattro/docs/testing.md). Run this before committing to ensure your modifications do not break existing behavior.

Summary

Setting up a development environment for Omarchy involves these key steps:

• Install development tools via the Omarchy menu to enable Mise and language runtimes.
• Execute omarchy channel-set dev to switch from stable to the development channel.
• Clone the repository to ~/omarchy and run omarchy dev link ~/omarchy to create the /etc/omarchy.conf binding.
• Run omarchy provision-user --first-install to initialize user-specific directories and symlinks.
• Use ./test/all to validate changes against the CLI, shell, and migration test suites.

Frequently Asked Questions

What is the Omarchy dev channel?

The dev channel is a runtime configuration that routes all omarchy-* commands to a local Git checkout rather than the system's packaged binaries. When you run omarchy channel-set dev, the system prepares to use live source code, and omarchy dev link creates the necessary /etc/omarchy.conf and sudoers configuration to make this redirection permanent.

How do I verify Mise is installed correctly?

After enabling the Development section in the Omarchy menu, open a terminal and run mise --version. The Mise binary is pre-bundled with Omarchy and manages Node.js, Python, Rust, and other language runtimes through version-specific shims documented in manual/18-development-tools.md.

Can I use a different directory than ~/omarchy for development?

Yes, you can clone the repository to any path. Simply substitute your custom path in the omarchy dev link command. For example: omarchy dev link /path/to/custom/omarchy. The linking mechanism updates /etc/omarchy.conf to point to whatever directory you specify.

How do I run only specific test suites instead of the full suite?

While ./test/all runs the complete validation, you can execute individual test components directly. Run ./test/shell for shell plugin tests or ./test/cli for command-line interface tests. Consult docs/testing.md for the specific test organization and how to run migration-specific tests independently.

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