Omarchy File Organization Structure: Complete Directory Layout Guide

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, 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:

# 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:

# Refresh Hyprland compositor configuration

omarchy-refresh-config hypr/hyprland.lua

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

# 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. Unlikedefault/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:

./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) 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.

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