Where to Find the Omarchy Source Code: Complete Guide to the basecamp/omarchy Repository

The Omarchy source code is hosted in the public GitHub repository basecamp/omarchy on the quattro branch, containing the full Linux environment including runtime binaries, installation scripts, migrations, themes, and documentation.

The Omarchy distribution is a full-stack Linux environment developed by Basecamp. If you are looking for the Omarchy source code to explore its architecture, customize your installation, or contribute to the project, everything is contained within a single public repository that maps cleanly to filesystem locations.

Official Repository Location

The canonical home for the Omarchy source code is the basecamp/omarchy repository on GitHub. Unlike many projects that split components across multiple repositories, Omarchy maintains its entire distribution—runtime binaries, shell UI, themes, and documentation—in one place.

To clone the repository correctly, you must specify the quattro branch, which serves as the main development branch:

git clone -b quattro https://github.com/basecamp/omarchy.git

Repository Structure and File Mapping

The Omarchy source code follows a deterministic layout where each directory maps to a specific location on a running Omarchy system. This design makes it straightforward to locate the source for any installed component.

Runtime Commands and Binaries

Files in bin/omarchy-* compile to /usr/bin/omarchy-* on the target system. The central dispatcher at bin/omarchy contains the GROUP_DESCRIPTIONS definitions that route subcommands to their appropriate handlers.

System Defaults and Configuration

The default/ directory seeds system-wide defaults into /usr/share/omarchy/default/, including environment bootstrap scripts and agent skill definitions located at default/agents/skills/omarchy/.

User Configuration Templates

The config/ path contains skeleton files that populate /etc/skel/.config/, providing new users with preconfigured settings for the Quickshell desktop and other applications.

Quickshell Desktop UI

The graphical shell implementation lives in shell/, which installs to /usr/share/omarchy/shell/. The entry point shell/shell.qml initializes the desktop environment and loads plugins from shell/plugins/panels/.

Installation and Migration Scripts

• install/ – Root-side installation scripts that deploy to /usr/share/omarchy/install/
• migrations/ – Per-user migration scripts stored in /usr/share/omarchy/migrations/, executed during system updates
• themes/ – Stock themes installed to /usr/share/omarchy/themes/

Documentation

The manual/ directory contains the source files for the official user documentation mirrored to https://learn.omacom.io, while docs/ holds architecture and developer documentation including the comprehensive File Layout description.

Key Source Files Reference

Navigate these specific files to understand core functionality:

• bin/omarchy – Central command dispatcher with subcommand routing logic
• shell/shell.qml – Quickshell desktop entry point
• docs/file-layout.md – Complete mapping documentation between repository paths and installed locations
• README.md – Project overview and quickstart guide
• manual/ – Source files for the official documentation website

Practical Source Code Operations

Once cloned, you can inspect, modify, and test components directly from the Omarchy source code:

Inspecting Runtime Commands

View the main binary source to understand available subcommands:

less bin/omarchy

Examining Shell Plugins

Panel plugins for the desktop environment reside in shell/plugins/panels/. For example, the Tailscale integration:

less shell/plugins/panels/tailscale/README.md

Running Manual Migrations

Execute specific migrations by referencing their timestamped filenames from the migrations/ directory:

omarchy-migrate 1786952219

Testing Configuration Changes

Refresh specific configuration segments after editing source files:

omarchy refresh-config hypr/hyprland.lua

Updating the System

Invoke the update mechanism that processes migration scripts:

omarchy update

Summary

• The Omarchy source code lives in the single public repository basecamp/omarchy on the quattro branch
• Repository paths map deterministically to filesystem locations: bin/ → /usr/bin/, shell/ → /usr/share/omarchy/shell/, and config/ → /etc/skel/.config/
• Key architectural documents reside in docs/file-layout.md and the root README.md
• The Quickshell desktop UI source is located in shell/shell.qml with plugins in shell/plugins/panels/
• Clone with git clone -b quattro https://github.com/basecamp/omarchy.git to get the complete distribution source

Frequently Asked Questions

What branch should I clone for the latest Omarchy source code?

Clone the quattro branch. While the repository may contain other branches, quattro serves as the main development branch containing the current stable environment configuration and all active migration scripts.

Where is the Quickshell desktop interface source located?

The Quickshell UI source resides in the shell/ directory, with the entry point at shell/shell.qml. When installed, these files deploy to /usr/share/omarchy/shell/, with panel plugins available in shell/plugins/panels/ such as the Tailscale integration.

How do repository paths map to installed system locations?

Omarchy uses a predictable mapping defined in docs/file-layout.md. Key mappings include bin/omarchy-* to /usr/bin/omarchy-*, default/ to /usr/share/omarchy/default/, migrations/ to /usr/share/omarchy/migrations/, and etc/ to /etc/. This structure allows direct correlation between the source tree and runtime locations.

Can I run individual components from the source without installing?

Yes. You can execute migration scripts directly from the migrations/ directory using omarchy-migrate [timestamp], and inspect binaries in bin/ before they are copied to /usr/bin/. However, the Quickshell desktop requires proper installation to /usr/share/omarchy/shell/ to function correctly within the Omarchy environment.

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