# Omarchy File Organization Structure: Complete Directory Layout Guide

> Explore the Omarchy file organization structure, detailing its directory layout for bin, default, docs, and test files. Learn how $OMARCHY_PATH controls runtime paths.

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

---

**Omarchy organizes its codebase into a clear, purpose-driven hierarchy that separates executable CLI scripts in `bin/`, default configuration assets in `default/`, documentation in `docs/`, and test suites in `test/`, with runtime paths controlled via the `$OMARCHY_PATH` environment variable.**

The `basecamp/omarchy` repository follows a strict directory convention designed to keep runtime code separate from source-only documentation and user-specific configurations. Understanding this file organization structure is essential for contributors modifying the CLI dispatcher or users customizing their desktop environment through Omarchy’s configuration system.

## Top-Level Directory Overview

The repository root—typically checked out as the *quattro* branch—contains seven primary directories and assorted metadata files. Each top-level folder serves a distinct architectural purpose:

- **`bin/`** – Executable bash wrappers that form the Omarchy CLI
- **`default/`** – Default configuration templates, themes, fonts, and menu definitions
- **`docs/`** – Human-readable Markdown documentation for developers
- **`agents/`** – Contributor skill documents and meta-guides
- **`test/`** – Automated CLI and shell integration tests
- **`default/agents/`** – Runtime agents invoked by the Omarchy daemon

Root-level files include [`AGENTS.md`](https://github.com/basecamp/omarchy/blob/main/AGENTS.md), `version`, and branding assets (`logo.*`, `icon.*`), which provide repository metadata but are not installed on target systems.

## The `bin/` Directory: CLI Command Wrappers

All user-facing Omarchy commands live in the **`bin/`** directory as individual bash scripts following the `omarchy-*` naming convention. Each script acts as a thin dispatcher that invokes the core runtime or helper utilities.

For example, `bin/omarchy-toggle-touchpad` handles touchpad state toggling, while `omarchy-refresh-config` manages configuration deployment. These files are shipped executable and remain in `$OMARCHY_PATH/bin` after installation.

The install script automatically adds `$OMARCHY_PATH/bin` to the user’s `$PATH`, enabling direct command invocation:

```bash

# Repository location

$OMARCHY_PATH/bin/omarchy-toggle-touchpad

# After installation (available via PATH)

omarchy toggle-touchpad

```

## The `default/` Directory: Configuration Assets and Themes

The **`default/`** directory contains factory settings that Omarchy copies into the user’s home directory on first run or when explicitly refreshed. This folder is organized into subdirectories for specific configuration domains:

- **`default/config/``** – Window manager configs, application settings, and shell initialization files
- **`default/themes/``** – Color schemes and appearance packages (symlinked to `$OMARCHY_PATH/themes/`)
- **`default/omarchy/``** – Menu definitions and runtime metadata
- **`default/fonts/``** – Typography assets for UI rendering
- **`default/agents/``** – Executable agents the Omarchy daemon invokes for menu generation and notifications

The helper `omarchy-refresh-config` uses `$OMARCHY_PATH/config` (a symlink pointing to `default/config/`) as its source. When refreshing configurations, it copies files to `~/.config/` while preserving existing user files with backups:

```bash

# Refresh Hyprland compositor configuration

omarchy-refresh-config hypr/hyprland.lua

```

Themes reside under `$OMARCHY_PATH/themes/` and are managed through dedicated CLI commands:

```bash

# List available themes

omarchy-theme-list

# Activate solarized-dark theme

omarchy-theme-set solarized-dark

```

## Documentation and Agents

The **`docs/``** folder contains Markdown files explaining Omarchy’s architecture, including [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md), [`docs/menu.md`](https://github.com/basecamp/omarchy/blob/main/docs/menu.md), and [`docs/theming.md`](https://github.com/basecamp/omarchy/blob/main/docs/theming.md). These files remain repository-only assets and are not installed on target systems.

The **`agents/``** directory holds contributor-facing documentation under `agents/skills/`, such as [`agents/skills/command-metadata.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/command-metadata.md), which describes how to add new `omarchy-*` commands. Unlike `default/agents/`, these documents are meta-guides for development and are excluded from runtime payloads.

## Testing Infrastructure

Quality assurance lives in the **`test/``** directory, separated by test type:

- **`test/all`** – Aggregates and executes the complete test suite (CLI + shell tests)
- **`test/cli`** – Command routing and argument parsing validation
- **`test/shell`** – Shell integration and environment setup verification

These files remain in the repository and execute locally via:

```bash
./test/all

```

No graphical acceptance tests are included in this directory; the suite focuses exclusively on CLI behavior and shell integration.

## Installation and Runtime Paths

Omarchy’s installation flow creates a clear separation between repository files and user configurations:

1. **Repository checkout** – The *quattro* branch checkout directory becomes `$OMARCHY_PATH`
2. **PATH modification** – `$OMARCHY_PATH/bin` is added to the user’s `$PATH` environment variable
3. **Configuration deployment** – Default files copy from `$OMARCHY_PATH/default/config/` to `~/.config/` only when explicitly refreshed or during initial setup
4. **Theme activation** – Active themes are symlinked from `$OMARCHY_PATH/themes/` into the user’s configuration tree (e.g., `~/.config/qtile/` or `~/.config/alacritty/`)

This architecture allows users to update Omarchy by pulling the latest *quattro* commit and re-running refresh commands without overwriting personal customizations.

## Summary

- **Executable commands** reside in `bin/` as `omarchy-*` bash scripts and become available through `$OMARCHY_PATH/bin` in the user PATH.
- **Default configurations** live in `default/config/`, copied to `~/.config/` via the `omarchy-refresh-config` utility.
- **Themes and fonts** are stored in `default/themes/` and `default/fonts/`, managed by `omarchy-theme-list` and `omarchy-theme-set`.
- **Documentation** in `docs/` and contributor guides in `agents/` remain repository-only and are never installed on target systems.
- **Test suites** in `test/` validate CLI routing and shell integration but stay confined to the source repository.
- **Runtime agents** differ from contributor documentation: `default/agents/` contains executable code, while `agents/` contains instructional Markdown.

## Frequently Asked Questions

### Where are Omarchy configuration files installed on my system?

User-specific configurations are installed in your home directory under `~/.config/`, populated by copying files from `$OMARCHY_PATH/default/config/` when you run `omarchy-refresh-config <relative-path>`. The system preserves existing files by creating backups before overwriting, ensuring your customizations remain safe during updates.

### How do I add the Omarchy CLI commands to my PATH?

The Omarchy install script automatically appends `$OMARCHY_PATH/bin` to your shell’s PATH variable, where `$OMARCHY_PATH` represents the root directory of your repository checkout. Once installed, you can execute any `omarchy-*` script directly by name, such as `omarchy toggle-touchpad` or `omarchy theme-set solarized-dark`.

### What is the difference between the `agents/` and `default/agents/` directories?

The **`agents/`** directory contains contributor documentation and skill guides (like [`agents/skills/command-metadata.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/command-metadata.md)) that explain how to extend Omarchy; these are instructional files excluded from runtime. The **`default/agents/`** directory contains executable scripts that the Omarchy daemon invokes during operation, such as menu generators and notification helpers, and these are actively loaded from `$OMARCHY_PATH/default/agents` at runtime.

### How do I update Omarchy without losing my personal configurations?

Update by pulling the latest commit from the *quattro* branch into your `$OMARCHY_PATH` directory, then selectively refresh only the configuration files you want to update using `omarchy-refresh-config`. Because Omarchy separates default templates in `default/` from live configurations in `~/.config/`, your personal settings remain untouched unless you explicitly overwrite them with the refresh command.