# omarchy | 37signals | Knowledge Base | Instagit

Beautiful, Modern & Opinionated Linux

GitHub Stars: 26k

Repository: https://github.com/basecamp/omarchy

---

## Articles

### [What Is Quickshell in Omarchy?](/basecamp/omarchy/what-is-quickshell-in-context-of-omarchy)

Discover Quickshell, Omarchy's core Wayland compositor and desktop toolkit. Learn how this single process powers your entire UI with dynamic JavaScript/QML plugins.

- Tags: deep-dive
- Published: 2026-08-29

### [How Omarchy Handles Shell Plugins: Discovery, Validation, and Activation](/basecamp/omarchy/how-does-omarchy-handle-shell-plugins)

Learn how Omarchy manages shell plugins. It discovers, validates, and activates extensions securely through a central PluginRegistry, ensuring only enabled plugins run.

- Tags: internals
- Published: 2026-08-29

### [What Is the Migration Framework in Omarchy? A Technical Deep Dive](/basecamp/omarchy/role-of-migration-framework-in-omarchy)

Discover Omarchy's migration framework: an automated system that uses ordered, idempotent shell scripts to synchronize user configurations with new releases. Streamline your upgrades.

- Tags: deep-dive
- Published: 2026-08-29

### [How Omarchy Manages Themes: Template-Driven Customization in Basecamp's Linux Desktop](/basecamp/omarchy/how-does-omarchy-manage-themes)

Discover how Omarchy manages themes with a template-driven system. Learn about shell commands, placeholder rendering, and protecting user overrides in Basecamp's Linux desktop.

- Tags: how-to-guide
- Published: 2026-08-29

### [What Does omarchy-provision-first-run Handle? Omarchy First-Run Provisioning Explained](/basecamp/omarchy/what-does-omarchy-provision-first-run-handle)

Learn what omarchy-provision-first-run handles: initializing Omarchy, enabling services, deploying configs, running migrations, and more. Ensure a smooth setup.

- Tags: internals
- Published: 2026-08-29

### [Idempotency Marker for omarchy-provision-user: File Location and Implementation Guide](/basecamp/omarchy/idempotency-marker-for-omarchy-provision-user)

Discover the idempotency marker for omarchy-provision-user, the finalize-user file, and learn how to prevent duplicate executions. Understand its implementation and `--force` flag.

- Tags: how-to-guide
- Published: 2026-08-29

### [How Skill Symlinks Are Managed in Omarchy User Provisioning](/basecamp/omarchy/how-are-skill-symlinks-managed-in-omarchy-user-provisioning)

Learn how Omarchy manages skill symlinks during user provisioning. Discover how centralized skills link to per-user directories for Claude, Codex, Pi, and Gemini.

- Tags: internals
- Published: 2026-08-29

### [What Does `omarchy finalize user` Do? Understanding the User Provisioning Script](/basecamp/omarchy/what-does-omarchy-finalize-user-do)

Learn what omarchy finalize user does to complete per-user setup, including symlinks, app configuration, and script sourcing. Understand user provisioning in Oarchy.

- Tags: deep-dive
- Published: 2026-08-29

### [Understanding the Role of /etc/skel in Omarchy User Setup](/basecamp/omarchy/role-of-etc-skel-in-omarchy-user-setup)

Discover how the /etc/skel directory in Omarchy seeds new user accounts with essential dotfiles and XDG configurations, streamlining user setup and personalization.

- Tags: how-to-guide
- Published: 2026-08-29

### [How Omarchy Populates a New User's Home Directory: Config Workflow Explained](/basecamp/omarchy/how-does-omarchy-populate-new-user-home-directory)

Learn how Omarchy populates a new user's home directory by copying default config files with the omarchy-refresh-config utility during first login.

- Tags: internals
- Published: 2026-08-29

### [Omarchy Command Naming Conventions: A Complete Guide to CLI Structure](/basecamp/omarchy/what-are-omarchy-command-naming-conventions)

Master Omarchy command naming conventions for structured CLI development. Learn the prefix and verb-group structure to build consistent and intuitive commands.

- Tags: best-practices
- Published: 2026-08-29

### [How Omarchy CLI Command Groups Are Defined: A Deep Dive into the Architecture](/basecamp/omarchy/how-are-omarchy-cli-command-groups-defined)

Discover how Omarchy CLI command groups are defined using the GROUP_DESCRIPTIONS associative array in the bin/omarchy script. Learn about automatic command discovery.

- Tags: deep-dive
- Published: 2026-08-29

### [How Omarchy Handles Arguments Passed to CLI Commands: Group-Command Dispatch Pattern](/basecamp/omarchy/how-does-omarchy-handle-arguments-passed-to-cli-commands)

Discover how Omarchy handles CLI arguments with its group-command dispatch pattern. Learn how scripts like bin/omarchy-group-command execute with forwarded arguments.

- Tags: internals
- Published: 2026-08-29

### [Understanding the Omarchy CLI Commands Dispatch Mechanic](/basecamp/omarchy/dispatch-mechanic-for-omarchy-cli-commands)

Discover how the Omarchy CLI dispatches commands. Learn about its fast path execution and metadata-driven route resolution for aliases and complex mappings.

- Tags: internals
- Published: 2026-08-29

### [How to Check Omarchy CLI Command Metadata for Errors](/basecamp/omarchy/how-to-check-omarchy-cli-command-metadata-for-errors)

Validate Omarchy CLI command metadata for errors with `omarchy commands --check`. Ensure correct formatting, routing, and required fields for robust command execution.

- Tags: how-to-guide
- Published: 2026-08-29

### [Omarchy CLI Commands Metadata Keys: Complete Reference Guide](/basecamp/omarchy/supported-metadata-keys-for-omarchy-cli-commands)

Explore Omarchy CLI commands and their metadata keys. Discover how group name summary args examples alias hidden and requires sudo control routing documentation and visibility for your scripts.

- Tags: api-reference
- Published: 2026-08-29

### [Understanding the Fallback Path in Omarchy CLI Command Resolution](/basecamp/omarchy/what-is-fallback-path-for-omarchy-cli-command-resolution)

Discover the Omarchy CLI fallback path for seamless command resolution. Learn how binaries like omarchy-new-project automatically map to omarchy new project without metadata.

- Tags: internals
- Published: 2026-08-29

### [What Is the Fast Path for Omarchy CLI Command Resolution?](/basecamp/omarchy/what-is-fast-path-for-omarchy-cli-command-resolution)

Discover the fast path for Omarchy CLI command resolution. Learn how hyphen-joined filenames speed up executable binary checks before metadata loading, avoiding comment block parsing overhead.

- Tags: internals
- Published: 2026-08-29

### [How the Omarchy CLI Router Resolves Commands: A Technical Deep Dive](/basecamp/omarchy/how-does-omarchy-cli-router-resolve-commands)

Explore how the Omarchy CLI router resolves commands using longest-prefix matching, metadata extraction, and exec dispatch for efficient command execution.

- Tags: deep-dive
- Published: 2026-08-29

### [Omarchy File Layout Convention: Repository Structure and System Mapping](/basecamp/omarchy/what-is-the-file-layout-convention-in-omarchy-repository)

Discover the Omarchy file layout convention. Learn how the repository structure maps to system paths for runtime binaries, configuration seeds, and assets. Understand the basecamp/omarchy organization.

- Tags: architecture
- Published: 2026-08-29

### [Where Are the PKGBUILDs for Omarchy Located?](/basecamp/omarchy/where-are-the-pkgbuilds-for-omarchy-located)

Find PKGBUILDs for Omarchy in the separate omarchy-pkgs repository within the pkgbuilds directory. Learn where to access these essential build files.

- Tags: how-to-guide
- Published: 2026-08-29

### [How Omarchy Is Distributed as Arch Linux Packages](/basecamp/omarchy/how-is-omarchy-distributed-as-arch-linux-packages)

Learn how Omarchy is distributed as Arch Linux packages. Install Omarchy easily using pacman with our PKGBUILD files and official repository.

- Tags: how-to-guide
- Published: 2026-08-29

### [How the Omarchy Test Suite Works: CLI, Shell, and Acceptance Testing](/basecamp/omarchy/how-does-the-omarchy-test-suite-work-cli-shell-acceptance)

Discover how the Omarchy test suite operates across CLI validation, shell plugin verification, and graphical acceptance testing for robust automated testing.

- Tags: how-to-guide
- Published: 2026-08-28

### [What Is the Omarchy First-Run Provisioning Script and How Does It Work?](/basecamp/omarchy/what-is-the-omarchy-first-run-provisioning-script)

Discover the Omarchy first-run provisioning script at basecamp/omarchy bin/omarchy-provision-first-run. Automate initial system configuration with owner and user setup tasks.

- Tags: how-to-guide
- Published: 2026-08-28

### [How the Omarchy CLI Router Dispatches Commands: Anatomy of the Entry Point](/basecamp/omarchy/how-does-the-omarchy-cli-router-dispatch-commands)

Discover how the Omarchy CLI router dispatches commands by parsing arguments, validating groups, and executing binaries. Understand the entry point's mechanism.

- Tags: internals
- Published: 2026-08-28

### [How Font Size and Typography Tokens Scale in Omarchy Themes](/basecamp/omarchy/how-do-font-size-and-typography-tokens-scale-in-omarchy-themes)

Learn how font size and typography tokens scale in Omarchy themes using shell.toml. Discover consistent text rendering across all UI elements.

- Tags: deep-dive
- Published: 2026-08-28

### [How the Omarchy Refresh Pattern Copies Default Configs: A Complete Technical Guide](/basecamp/omarchy/how-does-the-refresh-pattern-for-copying-default-omarchy-configs-work)

Discover how the Omarchy refresh pattern safely copies default configs to your user directory. Learn about its backup and diff process to preserve customizations. Complete technical guide.

- Tags: deep-dive
- Published: 2026-08-28

### [How the Omarchy Update Process Works: End-to-End Orchestration Explained](/basecamp/omarchy/how-does-the-end-to-end-omarchy-update-process-work)

Discover how the Omarchy update process works. Learn about orchestrated lock-protected checks, snapshots, upgrades, migrations, and cleanup managed by the omarchy-update command.

- Tags: internals
- Published: 2026-08-28

### [Understanding the omarchy-menu.jsonc Schema and Dynamic Menu Providers](/basecamp/omarchy/what-is-the-omarchy-menu.jsonc-schema-and-how-do-providers-work)

Explore the omarchy-menu.jsonc schema to define your menu hierarchy and learn how dynamic menu providers generate submenus at runtime in Omarchy.

- Tags: deep-dive
- Published: 2026-08-28

### [How Idle, Lock, and Screensaver Are Configured in Omarchy](/basecamp/omarchy/how-is-the-idle-lock-and-screensaver-configured-in-omarchy)

Configure Omarchy idle, lock, and screensaver settings in shell.json. Learn how the idle service plugin manages system idle time and triggers actions with default delays.

- Tags: how-to-guide
- Published: 2026-08-28

### [How the Spacing Scale System Works in Omarchy Shell Themes](/basecamp/omarchy/how-does-the-spacing-scale-system-work-in-omarchy-shell-themes)

Learn how Omarchy shell themes use a unified spacing scale for consistent design. Discover global multipliers, font-relative scaling, and per-token overrides for precise control.

- Tags: deep-dive
- Published: 2026-08-28

### [How the Dual-Package Build System Works in omarchy-pkgs](/basecamp/omarchy/how-does-the-dual-package-build-system-work-in-omarchy-pkgs)

Discover how omarchy-pkgs dual-package build system creates synchronized omarchy and omarchy-settings packages from a single source, preventing conflicts and ensuring version consistency.

- Tags: internals
- Published: 2026-08-28

### [Understanding the omarchy-dev-link Development Workflow in Basecamp's Omarchy](/basecamp/omarchy/what-is-the-omarchy-dev-link-development-workflow)

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.

- Tags: how-to-guide
- Published: 2026-08-28

### [How to Create and Install a Third-Party Plugin for Omarchy: A Complete Guide](/basecamp/omarchy/how-do-i-create-and-install-a-third-party-plugin-for-omarchy)

Learn to create and install a third-party plugin for Omarchy. Follow this guide to initialize a Git repository, add a manifest file, and install your plugin with the CLI.

- Tags: how-to-guide
- Published: 2026-08-28

### [How the Interactive State System ([controls]) Works in Omarchy Themes](/basecamp/omarchy/how-does-the-interactive-state-system-controls-work-in-omarchy-themes)

Learn how Omarchy themes use the [controls] system for consistent interactive UI styling. Discover runtime updates and unified token sets for buttons, dropdowns, and focus states.

- Tags: internals
- Published: 2026-08-28

### [Omarchy User Provisioning and Finalization Process: Three-Phase Setup Explained](/basecamp/omarchy/what-is-the-omarchy-user-provisioning-and-finalization-process)

Master Omarchy user provisioning with our three-phase setup Seed Finalize Resync. Learn how to separate static file copying from runtime configuration for efficient ISO installations.

- Tags: deep-dive
- Published: 2026-08-28

### [How to Add a Custom Bar Widget to the Omarchy Top Bar](/basecamp/omarchy/how-do-i-add-a-custom-bar-widget-or-inline-module-to-the-omarchy-top-bar)

Easily add a custom bar widget to the Omarchy top bar by creating a QML component and placing it in the correct directory. Omarchy automatically discovers and loads your widget.

- Tags: how-to-guide
- Published: 2026-08-28

### [How the Omarchy IPC System Enables Communication Between CLI and Shell](/basecamp/omarchy/how-does-the-ipc-system-enable-communication-between-cli-and-shell)

Discover how the Omarchy IPC system enables seamless communication between your CLI and shell using Unix sockets and JSON-encoded RPC calls for efficient data exchange.

- Tags: internals
- Published: 2026-08-28

### [How the Omarchy Desktop Is Configured Using shell.json: A Complete Guide](/basecamp/omarchy/how-is-the-omarchy-desktop-configured-using-shell.json)

Learn how to configure the Omarchy desktop using shell.json. This guide covers UI configuration, user overrides, hot-reloading, and inline plugin settings.

- Tags: how-to-guide
- Published: 2026-08-28

### [How the env-bootstrap System Configures OMARCHY_PATH and PATH in Omarchy](/basecamp/omarchy/how-does-the-env-bootstrap-system-configure-omarchy-path-and-path)

Discover how the env-bootstrap system in Omarchy configures OMARCHY_PATH and PATH, prioritizing development binaries and managing user tools for efficient environment setup.

- Tags: how-to-guide
- Published: 2026-08-28

### [Understanding the Difference Between Omarchy and Omarchy-Settings Packages](/basecamp/omarchy/what-is-the-difference-between-omarchy-and-omarchy-settings-packages)

Learn the key differences between omarchy and omarchy-settings packages. Understand how omarchy-settings handles baseline configuration and omarchy manages runtime execution.

- Tags: deep-dive
- Published: 2026-08-28

### [Omarchy Shell Theme Token System: How Quickshell Manages Theming](/basecamp/omarchy/what-is-the-omarchy-theme-token-system-for-the-shell)

Discover the Omarchy theme token system for shell theming. Learn how Quickshell uses TOML and QML singletons for consistent, state-aware desktop theming.

- Tags: internals
- Published: 2026-08-28

### [How the Omarchy Migration System Works: A Complete Guide to Writing Safe Per-User Updates](/basecamp/omarchy/how-does-the-omarchy-migration-system-work-and-how-do-i-write-a-new-migration)

Learn how Omarchy's migration system applies per-user updates safely. This guide covers writing new migrations and ensures idempotent execution for your package state.

- Tags: how-to-guide
- Published: 2026-08-28

### [How the Quickshell Plugin System Works in Omarchy: Architecture and Runtime Flow](/basecamp/omarchy/how-does-the-quickshell-plugin-system-work-in-omarchy)

Discover Omarchy's Quickshell plugin system architecture and runtime flow. Learn how dynamic registries and hot-swapping enable seamless extension loading without compositor restarts.

- Tags: architecture
- Published: 2026-08-28

### [Omarchy Shell Theme Tokens: Complete Configuration Guide](/basecamp/omarchy/what-theme-tokens-are-exposed-by-the-omarchy-shell)

Explore the Omarchy shell theme tokens for deep customization. This guide covers configuring colors, spacing, typography, and component states via TOML.

- Tags: how-to-guide
- Published: 2026-08-27

### [Omarchy Template Helpers: Complete Guide to Theme Variables](/basecamp/omarchy/what-are-the-available-helpers-in-the-omarchy-template-system)

Explore Omarchy template helpers and theme variables to customize your configurations. Learn how to inject colors and derived values into your .tpl files with this comprehensive guide.

- Tags: getting-started
- Published: 2026-08-27

### [How the Omarchy Template System Works: A Declarative Theming Pipeline](/basecamp/omarchy/how-does-the-omarchy-template-system-work)

Discover how the Omarchy template system works. This declarative pipeline renders static .tpl files into configuration files using a theme's color palette.

- Tags: internals
- Published: 2026-08-27

### [Omarchy Theme Activation Flow: Complete Pipeline Guide](/basecamp/omarchy/what-is-the-omarchy-theme-activation-flow)

Understand the Omarchy theme activation flow. Learn how Omarchy sets themes, applies overlays, renders templates, and updates your environment for a seamless experience.

- Tags: deep-dive
- Published: 2026-08-27

### [How to Check for Pending Migrations in Omarchy](/basecamp/omarchy/how-to-check-for-pending-migrations-in-omarchy)

Easily check for pending migrations in Omarchy using the omarchy-migrate --pending command. Discover incomplete migrations efficiently by scanning your project.

- Tags: how-to-guide
- Published: 2026-08-27

### [How to Run Pending Migrations in Omarchy: Complete Command Guide](/basecamp/omarchy/how-to-run-pending-migrations-in-omarchy)

Learn how to run pending migrations in Omarchy using the omarchy-migrate command. Execute or list unapplied scripts easily with this complete guide.

- Tags: how-to-guide
- Published: 2026-08-27

### [How to Write Omarchy Migrations: Rules and Best Practices](/basecamp/omarchy/what-are-the-rules-for-writing-omarchy-migrations)

Learn Omarchy migration rules and best practices. Discover how these idempotent shell scripts synchronize user installations after updates with omarchy-migrate.

- Tags: best-practices
- Published: 2026-08-27

### [How Omarchy Migrations Are Stored and Executed: Complete Technical Guide](/basecamp/omarchy/how-are-omarchy-migrations-stored-and-executed)

Learn how Omarchy migrations store and execute configuration changes as timestamped shell scripts. This technical guide explains the process and tracking mechanisms.

- Tags: deep-dive
- Published: 2026-08-27

### [Omarchy User Finalization: The 9-Step Provisioning Process Explained](/basecamp/omarchy/what-are-the-steps-involved-in-omarchy-user-finalization)

Master Omarchy user finalization with our 9-step provisioning guide. Learn how to transform a basic home directory into a fully functional desktop with AI skills and custom configurations.

- Tags: how-to-guide
- Published: 2026-08-27

### [How omarchy-reinstall-configs Resets Your Omarchy Configuration to Defaults](/basecamp/omarchy/how-does-omarchy-reinstall-configs-work)

Learn how omarchy-reinstall-configs resets your Omarchy configuration to defaults by overwriting your home directory with pristine /etc/skel files. Understand this destructive resynchronization.

- Tags: how-to-guide
- Published: 2026-08-27

### [What Does `omarchy-provision-user` Do? Automating Per-User Setup in Omarchy](/basecamp/omarchy/what-does-omarchy-provision-user-do)

Discover what omarchy-provision-user does. Automate per-user setup in Omarchy by creating symlinks, XDG directories, and default apps that /etc/skel cannot handle.

- Tags: how-to-guide
- Published: 2026-08-27

### [How Omarchy Populates the User Home Directory: The Three-Layer System](/basecamp/omarchy/what-are-the-three-layers-for-populating-the-user-s-home-directory-in-omarchy)

Discover Omarchy's three-layer system Seed, Finalize, and Resync for populating user home directories. Learn how static, dynamic, and refresh capabilities work together.

- Tags: internals
- Published: 2026-08-27

### [How the OMARCHY_PATH Environment Variable Is Managed in Omarchy](/basecamp/omarchy/how-is-the-omarchy-path-environment-variable-managed)

Learn how the OMARCHY_PATH environment variable is initialized, its default location, and how to override it in Omarchy for custom installations.

- Tags: internals
- Published: 2026-08-27

### [What Is the Purpose of `default/bash/env-bootstrap` in Omarchy?](/basecamp/omarchy/what-is-the-purpose-of-default-bash-env-bootstrap-in-omarchy)

Discover how Omarchy's default/bash/env-bootstrap script initializes your environment. It creates a consistent PATH for reliable tooling across shells.

- Tags: internals
- Published: 2026-08-27

### [How to Validate Omarchy CLI Metadata: 4 Essential Validation Rules](/basecamp/omarchy/how-to-validate-omarchy-cli-metadata)

Learn how to validate Omarchy CLI metadata using four essential rules. Ensure correct fields, data types, unique prefixes, and existing binaries for robust validation.

- Tags: how-to-guide
- Published: 2026-08-27

### [How to List Non-Hidden Commands in Omarchy](/basecamp/omarchy/how-to-list-non-hidden-commands-in-omarchy)

Easily list non-hidden commands in Omarchy. Discover how to view only visible commands or generate a programmatic list with this quick Omarchy guide.

- Tags: how-to-guide
- Published: 2026-08-27

### [How Command Groups Are Defined in Omarchy: The GROUP_DESCRIPTIONS Registry Explained](/basecamp/omarchy/how-are-command-groups-defined-in-omarchy)

Discover how command groups are defined in Omarchy using the GROUP_DESCRIPTIONS registry. Learn how prefixes map to descriptions for clear CLI help output.

- Tags: internals
- Published: 2026-08-27

### [Supported Metadata Keys in Omarchy Command Headers](/basecamp/omarchy/what-metadata-keys-are-supported-in-omarchy-command-headers)

Discover supported metadata keys in Omarchy command headers like summary, args, and alias. Omarchy uses these keys to generate help output, enforce permissions, and route commands.

- Tags: api-reference
- Published: 2026-08-27

### [How Command Metadata Is Loaded in Omarchy: The bin/omarchy Discovery Mechanism](/basecamp/omarchy/how-is-command-metadata-loaded-in-omarchy)

Discover how Omarchy loads command metadata by scanning bin/omarchy scripts and parsing comment annotations for instant runtime lookup. Learn the discovery mechanism.

- Tags: internals
- Published: 2026-08-27

### [Longest-Prefix Matching in Omarchy CLI Resolution: How Commands Are Routed](/basecamp/omarchy/what-is-longest-prefix-matching-in-omarchy-cli-resolution)

Discover how Omarchy CLI resolution uses longest-prefix matching to route commands. Understand argument parsing and command selection for efficient CLI design.

- Tags: deep-dive
- Published: 2026-08-27

### [How the Omarchy CLI Router Maps Commands: File-Based Dispatch Explained](/basecamp/omarchy/how-does-the-omarchy-cli-router-map-commands)

Discover how the Omarchy CLI router maps commands using file-based dispatch and longest-prefix matching to execute scripts in your bin directory.

- Tags: internals
- Published: 2026-08-27

### [What Are the Key Directories in the Omarchy Repository? A Complete Architecture Guide](/basecamp/omarchy/what-are-the-key-directories-in-the-omarchy-repository)

Explore the Omarchy repository's key directories like bin shell default config and more. Understand the architecture of this Linux desktop configuration suite.

- Tags: architecture
- Published: 2026-08-27

### [How Omarchy Is Structured Into Arch Packages: Core, Optional, and Meta-Packages Explained](/basecamp/omarchy/how-is-omarchy-structured-into-arch-packages)

Understand Omarchy's Arch package structure: core, optional, and meta-packages. Learn how this modular desktop environment is organized and provisioned.

- Tags: architecture
- Published: 2026-08-27

### [How Omarchy Blocks Direct pacman -Syu to Protect System Updates](/basecamp/omarchy/how-omarchy-update-process-prevent-direct-pacman-syu)

Learn how Omarchy prevents direct pacman -Syu by using an ALPM hook to guard system updates. Discover how to bypass this protection when needed.

- Tags: internals
- Published: 2026-08-26

### [How to Refresh the Omarchy Menu Configuration: A Complete Guide](/basecamp/omarchy/how-to-refresh-omarchy-menu-configuration)

Refresh Omarchy menu configuration easily. Use the omarchy-refresh-config command to update defaults, creating automatic backups. A complete guide for the basecamp/omarchy repository.

- Tags: how-to-guide
- Published: 2026-08-26

### [How to Use Providers for Dynamic Menu Content in Omarchy: A Complete Guide](/basecamp/omarchy/how-to-use-providers-dynamic-menu-content-omarchy)

Learn how to use Omarchy providers to generate dynamic menu content at runtime. Populate submenus with Bash commands or QML logic from JSONC files.

- Tags: how-to-guide
- Published: 2026-08-26

### [How Omarchy Menu Guards Control Visibility, Availability, and State](/basecamp/omarchy/how-do-guards-work-omarchy-menu-system)

Discover how Omarchy menu guards use shell scripts in JSON-C to control item visibility, availability, and state. Optimize your menu system with dynamic runtime evaluations.

- Tags: how-to-guide
- Published: 2026-08-26

### [How to Define and Structure Menus in Omarchy](/basecamp/omarchy/how-to-define-and-structure-menus-omarchy)

Learn to define and structure menus in Omarchy using declarative JSONC configuration. Build hierarchical menus rendered as a dmenu-style picker with Qt Quick.

- Tags: how-to-guide
- Published: 2026-08-26

### [How to Update Omarchy Themes: A Complete Guide to Managing Extra Themes](/basecamp/omarchy/how-to-update-installed-omarchy-themes)

Easily update your installed Omarchy themes with our comprehensive guide. Learn how to manage extra themes and keep your customizations current using the omarchy-theme-update command.

- Tags: how-to-guide
- Published: 2026-08-26

### [How to Install a New Theme for Omarchy from a Git Repository](/basecamp/omarchy/how-to-install-new-theme-omarchy-git-repository)

Install a new Omarchy theme from a Git repository easily. Clone the theme, place it in the config directory, and restart your shell to apply the new palette.

- Tags: how-to-guide
- Published: 2026-08-26

### [How to Apply a Theme in Omarchy: CLI, UI, and Custom Configuration Methods](/basecamp/omarchy/how-to-apply-theme-omarchy)

Learn how to apply a theme in Omarchy using the CLI, hotkey, or status bar. Customize your Omarchy experience with these easy methods.

- Tags: how-to-guide
- Published: 2026-08-26

### [How the Omarchy Theme System Generates Configuration Files: Staging, Rendering, and Activation](/basecamp/omarchy/how-does-omarchy-theme-system-generate-configuration-files)

Learn how Omarchy generates configuration files by staging, overlaying customizations, rendering templates, and atomically activating the result for your themes.

- Tags: internals
- Published: 2026-08-26

### [How to Rescan and Reload Plugins in the Omarchy Shell](/basecamp/omarchy/how-to-rescan-reload-plugins-omarchy-shell)

Quickly rescan and reload plugins in the Omarchy shell with a simple command. Keep your Omarchy session updated without interruption. Learn how to trigger a hot-reload now.

- Tags: how-to-guide
- Published: 2026-08-26

### [How to Reload the Omarchy Shell Configuration: 3 Methods Explained](/basecamp/omarchy/how-to-reload-omarchy-shell-configuration)

Reload Omarchy shell configuration instantly with three methods. Apply changes to shell.json without restarting your Wayland compositor. Learn how now.

- Tags: how-to-guide
- Published: 2026-08-26

### [How to Restart the Omarchy Shell: Complete Command Guide](/basecamp/omarchy/how-to-restart-omarchy-shell)

Safely restart the Omarchy shell with the omarchy-restart-shell command. Learn to terminate processes and launch new sessions with automatic lock file cleanup.

- Tags: how-to-guide
- Published: 2026-08-26

### [How Quickshell Plugins Are Declared and Managed in Omarchy](/basecamp/omarchy/how-are-plugins-declared-and-managed-quickshell)

Discover how Quickshell plugins are declared and managed in Omarchy using a manifest-driven registry. Learn about manifest.json and PluginRegistry for seamless plugin integration.

- Tags: internals
- Published: 2026-08-26

### [IPC Methods Available for the Omarchy Shell: Complete API Reference](/basecamp/omarchy/what-ipc-methods-are-available-for-omarchy-shell)

Explore Omarchy shell IPC methods for remote theme application, plugin management, and more. Access 13 public IPC methods via IpcHandler for external script and DBus client integration.

- Tags: api-reference
- Published: 2026-08-26

### [How to Communicate with the Omarchy Shell via CLI: A Complete IPC Guide](/basecamp/omarchy/how-to-communicate-with-omarchy-shell-via-cli)

Learn to communicate with the Omarchy shell via CLI using Unix sockets and JSON commands. This guide provides a complete IPC solution for scriptable desktop environment control.

- Tags: how-to-guide
- Published: 2026-08-26

### [How the Quickshell Desktop Framework Powers Omarchy: Architecture and Implementation](/basecamp/omarchy/how-does-quickshell-desktop-framework-work-omarchy)

Discover how the Quickshell desktop framework powers Omarchy. Explore its layered architecture, connecting Bash utilities, system services, and QML plugins via JavaScript APIs.

- Tags: architecture
- Published: 2026-08-26

### [Understanding Metadata Comments in Omarchy Commands: A Complete Guide](/basecamp/omarchy/what-is-role-of-metadata-comments-omarchy-commands)

Master Omarchy metadata comments. Learn how these annotations override routing, define groups, set descriptions, and control visibility to enhance your command line tools.

- Tags: how-to-guide
- Published: 2026-08-26

### [How to Get the Omarchy Command List as JSON Output](/basecamp/omarchy/how-to-get-omarchy-command-list-as-json-output)

Effortlessly export your omarchy command list as JSON using the simple --json flag. Get structured output for seamless integration with your tools.

- Tags: how-to-guide
- Published: 2026-08-26

### [How to Check for Route Collisions in Omarchy Commands](/basecamp/omarchy/how-to-check-route-collisions-omarchy-commands)

Discover how to check for route collisions in Omarchy commands. Run the static conflict test or use omarchy cmd present to prevent duplicate routes and ensure smooth operation.

- Tags: how-to-guide
- Published: 2026-08-26

### [How to Get Help for a Specific omarchy Command: CLI Guide](/basecamp/omarchy/how-to-get-help-for-specific-omarchy-command)

Easily find help for any omarchy command using --help or help subcommand. Get detailed usage, options, and examples for the omarchy CLI.

- Tags: how-to-guide
- Published: 2026-08-26

### [How to List All Available Omarchy Commands: Complete CLI Reference](/basecamp/omarchy/how-to-list-all-available-omarchy-commands)

Easily list all available omarchy commands with `omarchy commands`. Access a complete CLI reference for the basecamp/omarchy repository and enhance your workflow.

- Tags: api-reference
- Published: 2026-08-26

### [How Omarchy Handles Command Aliases and Metadata Overrides](/basecamp/omarchy/how-omarchy-handle-command-aliases-and-metadata-overrides)

Discover how Omarchy parses Bash script header comments into key-value metadata for dynamic alias routing and handles metadata overrides.

- Tags: how-to-guide
- Published: 2026-08-26

### [Omarchy Theme Templates Placeholder Syntax: A Complete Guide](/basecamp/omarchy/what-placeholder-syntax-available-omarchy-theme-templates)

Master Omarchy theme templates placeholder syntax with our complete guide. Learn to use mustache double curly braces for variable substitution and string concatenation effectively.

- Tags: deep-dive
- Published: 2026-08-25

### [How Omarchy’s Template System Works for Theme Generation: A Deep Dive into the Palette-to-Config Pipeline](/basecamp/omarchy/how-omarchy-template-system-work-theme-generation)

Discover how Omarchy's template system generates themes by resolving color palettes, rendering tpl templates with sed, and applying shell overrides. Learn about the palette-to-config pipeline.

- Tags: deep-dive
- Published: 2026-08-25

### [What Is the Purpose of colors.toml in an Omarchy Theme?](/basecamp/omarchy/purpose-of-colors-toml-in-omarchy-theme)

Discover how colors.toml defines the semantic color palette for Omarchy themes, influencing the entire desktop environment's look and feel.

- Tags: deep-dive
- Published: 2026-08-25

### [Where Are Omarchy Themes Stored and How Are They Structured?](/basecamp/omarchy/where-omarchy-themes-stored-how-structured)

Discover where Omarchy themes are stored and how they are structured. Learn about stock and custom theme locations, colors.toml, and UI configuration files like shell.toml and hyprland.lua.

- Tags: how-to-guide
- Published: 2026-08-25

### [How to Use BorderSurface with Omarchy Theme Tokens in QML](/basecamp/omarchy/how-to-use-bordersurface-omarchy-theme-tokens-qml)

Learn to use BorderSurface with Omarchy theme tokens in QML. Optimize backgrounds and borders with hardware-accelerated rendering or custom Shape overlays for complex designs.

- Tags: how-to-guide
- Published: 2026-08-25

### [Omarchy Shell Theme Tokens: Color, Style, and Border Reference](/basecamp/omarchy/what-are-omarchy-shell-theme-tokens)

Explore Omarchy shell theme tokens for Color, Style, and Border. This QML-based system defines UI component appearance in basecamp/omarchy.

- Tags: api-reference
- Published: 2026-08-25

### [How to Declare Custom Bar Modules Inline in Omarchy's shell.json](/basecamp/omarchy/can-declare-custom-bar-modules-inline-omarchy-shell-json)

Learn to declare custom bar modules inline in Omarchy shell.json using command or qml types. Render modules at runtime without separate plugin registration.

- Tags: how-to-guide
- Published: 2026-08-25

### [How to Configure the Omarchy Bar Using shell.json](/basecamp/omarchy/how-omarchy-bar-configured-using-shell-json)

Learn how to configure the Omarchy bar using shell.json. Customize position transparency widget layout and plugins easily in this essential guide.

- Tags: how-to-guide
- Published: 2026-08-25

### [How to Apply Themes and Shell Configurations to the Omarchy Shell via IPC](/basecamp/omarchy/how-to-apply-themes-shell-configs-omarchy-shell-ipc)

Learn to apply themes and shell configurations to Omarchy via IPC. Use the omarchy-shell command and verbs like setTheme or applyConfig for live updates without restarting.

- Tags: how-to-guide
- Published: 2026-08-25

### [Omarchy Shell IPC Methods for CLI Communication: Complete API Reference](/basecamp/omarchy/what-ipc-methods-omarchy-shell-expose-cli-communication)

Explore Omarchy shell IPC methods for CLI communication. Learn to control your UI scriptably with ping, summon, hide, and more. Full API reference included.

- Tags: api-reference
- Published: 2026-08-25

### [How Third-Party Plugins Are Installed and Managed in Omarchy](/basecamp/omarchy/how-third-party-plugins-installed-managed-omarchy)

Discover how Omarchy installs and manages third-party plugins by cloning Git repos and updating a JSON registry. Learn the CLI commands for seamless integration.

- Tags: how-to-guide
- Published: 2026-08-25

### [Quickshell Shell Plugin Kinds: The Complete Guide to Omarchy UI Architecture](/basecamp/omarchy/supported-plugin-kinds-quickshell-shell)

Explore the ten Quickshell plugin kinds for Omarchy UI architecture: bar, panel, overlay, service, background, menu, notification, osd, and agent. Learn how UI elements integrate with the shell.

- Tags: deep-dive
- Published: 2026-08-25

### [Quickshell Plugin manifest.json: Complete Field Reference for Omarchy](/basecamp/omarchy/what-information-in-quickshell-plugin-manifest-json)

Discover the Quickshell plugin manifest.json structure. Learn about essential fields like id, name, kind, and entry needed to register your plugin with Omarchy.

- Tags: api-reference
- Published: 2026-08-25

### [How Omarchy's Plugin Architecture Works: A Technical Deep Dive](/basecamp/omarchy/how-omarchy-plugin-architecture-work)

Explore Omarchy's folder based plugin system. Learn how manifest.json files validate and load extensions dynamically into a registry for QML entry points.

- Tags: deep-dive
- Published: 2026-08-25

### [How to Launch and Restart the Omarchy Shell: A Complete Guide](/basecamp/omarchy/how-to-launch-restart-omarchy-shell)

Learn how to launch and restart the Omarchy shell. Easily respawn the Quickshell process with omarchy-restart-shell, preserving your Hyprland session state.

- Tags: how-to-guide
- Published: 2026-08-25

### [What Is the Quickshell Desktop Shell in Omarchy?](/basecamp/omarchy/what-is-quickshell-desktop-shell-omarchy)

Explore the Quickshell desktop shell in Omarchy, a single-process QML runtime. Discover how it loads UI components as plugins for a flexible and efficient user experience.

- Tags: deep-dive
- Published: 2026-08-25

### [How Omarchy’s CLI Performs Prefix Listing and Suggestions](/basecamp/omarchy/how-omarchy-cli-performs-prefix-listing-suggestions)

Discover how Omarchy's CLI dynamically lists commands by scanning bin files and suggests corrections using a Levenshtein algorithm for unmatched inputs.

- Tags: internals
- Published: 2026-08-25

### [What Is the `--` Separator in Omarchy CLI Commands?](/basecamp/omarchy/purpose-of-double-dash-separator-omarchy-cli-commands)

Understand the Omarchy CLI -- separator. It separates wrapper script arguments from underlying component arguments like qs IPC client. Learn its purpose now.

- Tags: internals
- Published: 2026-08-25

### [How Omarchy Handles `--help` and `-h` Arguments in Its CLI](/basecamp/omarchy/how-omarchy-handles-help-arguments-cli)

Discover how Omarchy handles --help and -h arguments. Learn about its early flag detection, usage info printing, and zero-code exit for efficient CLI interaction.

- Tags: how-to-guide
- Published: 2026-08-25

### [How Omarchy’s CLI Router Implements Two-Pass Dispatch Resolution](/basecamp/omarchy/explain-two-pass-dispatch-resolution-omarchy-cli-router)

Discover how Omarchy's CLI router uses two-pass dispatch resolution to efficiently map commands to scripts and handle arguments. Optimize your command-line workflow.

- Tags: internals
- Published: 2026-08-25

### [How Omarchy Handles Hidden Commands in Its CLI: Metadata Parsing and Filter Logic](/basecamp/omarchy/how-are-hidden-commands-handled-omarchy-cli)

Discover how Omarchy handles hidden commands in its CLI. Learn about metadata parsing and filter logic to exclude commands from default help listings.

- Tags: internals
- Published: 2026-08-25

### [Canonical vs Filename Routes in Omarchy: CLI Router Deep Dive](/basecamp/omarchy/difference-between-canonical-and-filename-routes-omarchy)

Understand canonical vs filename routes in Omarchy CLI. Learn how canonical routes override defaults using metadata for flexible command structures and backward compatibility.

- Tags: deep-dive
- Published: 2026-08-25

### [How Omarchy Commands Define Metadata: The Complete Guide to # omarchy: Comments](/basecamp/omarchy/how-is-metadata-defined-omarchy-commands)

Learn how Omarchy commands define metadata using special # omarchy comments. Discover how this metadata generates help text, validates arguments, and organizes menus in this comprehensive guide.

- Tags: deep-dive
- Published: 2026-08-25

### [Understanding the Naming Convention for Omarchy CLI Binaries](/basecamp/omarchy/what-is-naming-convention-omarchy-cli-binaries)

Discover the Omarchy CLI binary naming convention: omarchy-<group>-<name>. Understand how each segment defines the command structure for easy use.

- Tags: deep-dive
- Published: 2026-08-25

### [How Omarchy's CLI Router Dispatches Commands: A Deep Dive into Dynamic Command Routing](/basecamp/omarchy/how-does-omarchy-cli-router-dispatch-commands)

Discover how Omarchy's CLI router dynamically dispatches commands by scanning for executables, parsing metadata, and using a two-stage resolution strategy for efficient execution and automatic help generation.

- Tags: deep-dive
- Published: 2026-08-25

### [Omarchy Theme Activation Process: How the Staged Atomic Swap Works](/basecamp/omarchy/what-happens-during-the-omarchy-theme-activation-process)

Explore the Omarchy theme activation process and the 16-step staged atomic swap. Learn how inputs are validated, security filters applied, and UI hot-reloaded.

- Tags: how-to-guide
- Published: 2026-08-24

### [How the Omarchy Theming System Uses TOML for Color Definitions](/basecamp/omarchy/how-does-the-omarchy-theming-system-use-toml-for-color-definitions)

Explore how Omarchy uses TOML for color definitions. Learn how colors.toml files ensure consistent palettes across your desktop, terminal, and UI with omarchy-theme-set.

- Tags: how-to-guide
- Published: 2026-08-24

### [Where Are Omarchy Themes Stored and How They Work: Complete Guide](/basecamp/omarchy/where-are-omarchy-themes-stored-and-how-are-they-organized)

Discover where Omarchy themes are stored, from stock to custom user themes. Learn how Omarchy merges these directories for easy customization.

- Tags: how-to-guide
- Published: 2026-08-24

### [What Is the Purpose of shell.toml in Omarchy's Configuration?](/basecamp/omarchy/what-is-the-purpose-of-shelltoml-in-omarchys-configuration)

Discover the purpose of shell.toml in Omarchy's configuration. This file defines the visual language, including colors, states, spacing, and typography for QML components.

- Tags: internals
- Published: 2026-08-24

### [How to Enable Third-Party Plugins in Omarchy's shell.json](/basecamp/omarchy/how-are-third-party-plugins-enabled-in-omarchys-shelljson)

Easily enable third-party plugins in Omarchy by modifying your shell.json. Learn how to add descriptor objects to load QML components dynamically from the extensions directory.

- Tags: how-to-guide
- Published: 2026-08-24

### [Understanding the Omarchy shell.json Structure: State Management Schema Explained](/basecamp/omarchy/what-is-the-structure-of-the-omarchy-shelljson-state-management-file)

Explore the Omarchy shell.json structure. Understand the state management schema including version, bar layouts, and plugins for your desktop.

- Tags: internals
- Published: 2026-08-24

### [How to Enable a Plugin Using Omarchy’s IPC setPluginEnabled Method](/basecamp/omarchy/how-do-i-enable-a-plugin-using-omarchys-ipc-setpluginenabled-method)

Easily enable plugins in Omarchy with the setPluginEnabled method. Learn how to toggle plugins on using the command line for seamless integration. Get started now.

- Tags: how-to-guide
- Published: 2026-08-24

### [Omarchy Shell IPC Targets: Complete Guide to Inter-Process Communication Interfaces](/basecamp/omarchy/what-are-the-ipc-targets-exposed-by-the-omarchy-shell)

Discover the Omarchy shell IPC targets. Learn about the eleven explicit panel targets, core shell target, and six implicit service targets for seamless inter-process communication.

- Tags: deep-dive
- Published: 2026-08-24

### [How to Clone a Built‑in Omarchy Plugin to Your User Configuration](/basecamp/omarchy/how-can-i-clone-a-built-in-omarchy-plugin-to-my-user-configuration)

Easily clone an Omarchy built-in plugin to your user config using omarchy plugin clone. Customize plugins without altering system files and gain full editing freedom.

- Tags: how-to-guide
- Published: 2026-08-24

### [How Omarchy Handles Code Review for Third-Party Plugins: A Security-First Architecture](/basecamp/omarchy/how-does-omarchy-handle-code-review-for-third-party-plugins)

Learn how Omarchy secures third-party plugins with mandatory human review, cloning, diffs, and explicit enablement. Discover Omarchy's security-first architecture.

- Tags: architecture
- Published: 2026-08-24

### [Where Are Third-Party Quickshell Plugins Cloned in Omarchy?](/basecamp/omarchy/where-are-third-party-quickshell-plugins-cloned-by-users)

Discover where Omarchy clones third-party Quickshell plugins. Learn the exact directory path to manage your extensions effectively and enhance your workflow.

- Tags: how-to-guide
- Published: 2026-08-24

### [What Kinds of Plugins Can a Quickshell Plugin Declare? A Complete Guide to Quickshell Plugin Types](/basecamp/omarchy/what-are-the-different-kinds-of-plugins-a-quickshell-plugin-can-declare)

Discover the six Quickshell plugin kinds: bar, bar-widget, panel, overlay, menu, and service. Learn how these types define plugin behavior and UI placement in this complete guide.

- Tags: deep-dive
- Published: 2026-08-24

### [Quickshell Plugin manifest.json Structure in Omarchy: Complete Schema Guide](/basecamp/omarchy/what-is-the-structure-of-a-quickshell-plugin-manifestjson)

Understand the Quickshell plugin manifest.json structure in Omarchy. Learn about schemaVersion, id, kinds, and entryPoints for QML functionality. Get the complete schema guide now.

- Tags: api-reference
- Published: 2026-08-24

### [Understanding Omarchy Command Group Prefixes and Their Purposes](/basecamp/omarchy/what-are-the-different-command-group-prefixes-in-omarchy-and-their-purposes)

Explore Omarchy command group prefixes like cmd, capture, pkg, and theme. Understand their purposes and how they organize the Omarchy CLI for efficient use.

- Tags: deep-dive
- Published: 2026-08-24

### [How Routing Metadata Is Extracted from Omarchy CLI Binaries: A Deep Dive into the Self-Documenting Router](/basecamp/omarchy/how-are-routing-metadata-extracted-from-omarchy-cli-binaries)

Discover how Omarchy extracts routing metadata from CLI binaries by scanning structured comments and filenames. Learn about this self-documenting router for basecamp/omarchy.

- Tags: deep-dive
- Published: 2026-08-24

### [How the Omarchy CLI Router Discovers and Routes Commands](/basecamp/omarchy/how-does-omarchy-cli-router-system-discover-and-route-commands)

Learn how the Omarchy CLI router discovers commands by scanning bin/ for omarchy- executables and routes user input using an associative array mapping command names to file paths.

- Tags: internals
- Published: 2026-08-24

### [Where Are the PKGBUILDs for Omarchy Packages Located?](/basecamp/omarchy/where-are-the-pkgbuilds-for-omarchy-packages-located)

Find PKGBUILDs for Omarchy packages easily. Learn where these essential build files are located in the dedicated omarchy-pkgs repository, not the main basecamp/omarchy repo.

- Tags: how-to-guide
- Published: 2026-08-24

### [What Are the Two Main Arch Packages Omarchy Is Distributed As? A Complete AUR Guide](/basecamp/omarchy/what-are-the-two-main-arch-packages-omarchy-is-distributed-as)

Discover the two main Arch packages for Omarchy: omarchy for stable and omarchy-dev for development. Learn how to install Omarchy from the AUR with this complete guide.

- Tags: how-to-guide
- Published: 2026-08-24

### [How Omarchy Discovers and Manages Plugins: Complete Guide to the Quickshell Architecture](/basecamp/omarchy/how-does-omarchy-discover-and-manage-plugins)

Learn how Omarchy discovers and manages plugins using its Quickshell architecture. Explore filesystem scanning, manifest validation, and the plugin registry for seamless integration.

- Tags: architecture
- Published: 2026-08-24

### [Omarchy Shell Root QML Entry Point Location and Architecture](/basecamp/omarchy/where-is-the-entry-point-for-omarchy-shell-shellroot-qml)

Discover the Omarchy shell root QML entry point. Learn about shell.qml, the Quickshell runtime, and the QML UI architecture in this technical guide.

- Tags: architecture
- Published: 2026-08-24

### [How Omarchy Defines Its Core Runtime Path Using OMARCHY_PATH](/basecamp/omarchy/how-does-omarchy-define-its-core-runtime-path-using-omarachy_path)

Learn how Omarchy defines its core runtime path using the OMARCHY_PATH environment variable. Discover how this centralizes installation for every shell session in the Omarchy project.

- Tags: internals
- Published: 2026-08-24

### [Purpose of uwsm in Omarchy Desktop Session Management: A Complete Technical Guide](/basecamp/omarchy/what-is-the-purpose-of-uwsm-in-omarchy-desktop-session-management)

Discover the purpose of uwsm in Omarchy's desktop session management. Learn how uwsm bootstraps Wayland, manages session variables, and launches apps for a robust desktop experience.

- Tags: deep-dive
- Published: 2026-08-24

### [How Omarchy's Quickshell Architecture Improves Desktop Performance](/basecamp/omarchy/how-does-omarchy-quickshell-architecture-improve-performance)

Discover how Omarchy's Quickshell architecture enhances desktop performance through single-process QML composition, on-demand service loading, and lazy UI components for lower latency and memory usage.

- Tags: architecture
- Published: 2026-08-24

### [How to Resync User Configurations in Omarchy: The Complete Guide](/basecamp/omarchy/how-to-resync-user-configurations-in-omarchy)

Resync Omarchy user configurations by running omarchy-refresh-config. This command copies defaults from the repository, backing up existing settings and preserving your preferences.

- Tags: how-to-guide
- Published: 2026-08-23

### [What is `omarchy-provision-user`? Understanding Per-User Provisioning in Omarchy](/basecamp/omarchy/what-is-purpose-of-omarchy-provision-user)

Discover `omarchy-provision-user`, the Omarchy command that sets up individual user environments by seeding configs, running install scripts, and finalizing runtime settings.

- Tags: deep-dive
- Published: 2026-08-23

### [How to Configure a Custom QML Widget for the Bar in Omarchy](/basecamp/omarchy/how-to-configure-custom-qml-widget-for-bar-in-omarchy)

Learn to configure a custom QML widget for the Omarchy bar. Implement a QML Item, declare a plugin manifest, and use the omarchy bar put command for seamless integration.

- Tags: how-to-guide
- Published: 2026-08-23

### [How to Create Inline Bar Modules in Omarchy: A Complete Configuration Guide](/basecamp/omarchy/how-to-create-inline-bar-modules-in-omarchy)

Learn to create inline bar modules in Omarchy by configuring widget entries directly in bar.json. This guide simplifies widget instantiation without separate plugin files.

- Tags: how-to-guide
- Published: 2026-08-23

### [Omarchy vs Omarchy-Settings: Understanding the Difference Between the Runtime and Configuration Packages](/basecamp/omarchy/difference-between-omarchy-and-omarchy-settings-packages)

Understand the difference between Omarchy and Omarchy-settings packages. Discover how the runtime and configuration packages bootstrap your desktop environment.

- Tags: deep-dive
- Published: 2026-08-23

### [How Omarchy Manages User Configuration Files: The omarchy-refresh-config Workflow Explained](/basecamp/omarchy/how-does-omarchy-manage-user-configuration-files)

Discover how Omarchy manages user configuration files using the omarchy-refresh-config workflow. Learn how it safely copies defaults and backs up existing files.

- Tags: how-to-guide
- Published: 2026-08-23

### [Omarchy File Layout: Understanding the Repository Structure and System Integration](/basecamp/omarchy/what-is-file-layout-for-omarchy)

Explore the Omarchy file layout for the basecamp/omarchy repository. Understand how Arch packages map directories to system paths for seamless integration across user lifecycles.

- Tags: internals
- Published: 2026-08-23

### [How to Create a Custom Omarchy Theme: Complete Guide for Beginners](/basecamp/omarchy/how-to-create-custom-omarchy-theme)

Learn to create a custom Omarchy theme by following this beginner-friendly guide. Easily set your unique color scheme and personalize your Omarchy experience.

- Tags: how-to-guide
- Published: 2026-08-23

### [How to Apply a Theme in Omarchy: CLI, Menu, and Hotkey Methods](/basecamp/omarchy/how-to-apply-theme-in-omarchy)

Learn how to apply a theme in Omarchy using CLI, menu, or hotkey. Instantly change your desktop's look with our simple guide.

- Tags: how-to-guide
- Published: 2026-08-23

### [Omarchy Shell IPC Methods: Complete Guide to Inter-Process Communication](/basecamp/omarchy/what-are-ipc-methods-available-on-omarchy-shell)

Explore Omarchy shell IPC methods including socket-based communication and lifecycle verbs. Discover how plugins register targets for specialized commands in this comprehensive guide.

- Tags: deep-dive
- Published: 2026-08-23

### [How to Remove an Omarchy Plugin: CLI and Manual Methods](/basecamp/omarchy/how-to-remove-omarchy-plugin)

Learn how to remove an Omarchy plugin using the CLI command omarchy plugin remove or by manually deleting the plugin directory. Rescan the registry to complete the process.

- Tags: how-to-guide
- Published: 2026-08-23

### [How to Update Omarchy Plugins: A Complete Guide to Git-Managed Extensions](/basecamp/omarchy/how-to-update-omarchy-plugins)

Easily update Omarchy plugins with the omarchy plugin update command. This guide shows how to perform safe Git fast-forwards from your plugin directory, preserving local changes and reviewing diffs.

- Tags: how-to-guide
- Published: 2026-08-23

### [How to Install a Third-Party Omarchy Plugin: Complete CLI Guide](/basecamp/omarchy/how-to-install-third-party-omarchy-plugin)

Install and enable third-party Omarchy plugins using the CLI. This guide shows you how to clone, inspect, and activate custom plugins from any Git repository.

- Tags: how-to-guide
- Published: 2026-08-23

### [Omarchy Plugin Manifest Schema: Complete Developer Guide](/basecamp/omarchy/what-is-manifest-schema-for-omarchy-plugins)

Understand the Omarchy plugin manifest schema. Learn about schemaVersion, id, kinds, and entryPoints for defining plugin identity and QML files in manifest.json.

- Tags: api-reference
- Published: 2026-08-23

### [How to Define a Custom Bar Widget in Omarchy](/basecamp/omarchy/how-to-define-custom-bar-widget-in-omarchy)

Learn how to define a custom bar widget in Omarchy. Extend the BarWidget base class and register with BarWidgetRegistry to make your component visible in the UI.

- Tags: how-to-guide
- Published: 2026-08-23

### [Understanding the Different Plugin Kinds in Omarchy](/basecamp/omarchy/what-are-different-plugin-kinds-in-omarchy)

Explore the six plugin kinds in Omarchy: bar widget, panel, overlay, menu, service, and bar. Learn how Omarchy loads, displays, and manages components within its Quickshell process.

- Tags: deep-dive
- Published: 2026-08-23

### [How to Develop Omarchy Plugins: A Complete Guide to Building Desktop Extensions](/basecamp/omarchy/how-to-develop-omarchy-plugins)

Learn to develop Omarchy plugins by creating manifest files and QML entry points. This guide covers enabling extensions and using hot-reload for efficient desktop development.

- Tags: how-to-guide
- Published: 2026-08-23

### [How the Omarchy Plugin System Works: Architecture and Implementation Guide](/basecamp/omarchy/how-does-omarchy-plugin-system-work)

Discover the Omarchy plugin system architecture. Learn how this manifest-driven framework loads QML services, widgets, and menus while ensuring secure sandboxed paths.

- Tags: architecture
- Published: 2026-08-23

### [How Omarchy CLI Commands Are Organized: Directory Structure and Routing](/basecamp/omarchy/how-are-omarchy-cli-commands-organized)

Discover how Omarchy CLI commands are organized using a hierarchical naming convention and centralized routing in bin/omarchy. Understand the directory structure and command patterns for efficient use.

- Tags: internals
- Published: 2026-08-23

### [What Is Quickshell in Omarchy? Understanding the Desktop Construction Kit](/basecamp/omarchy/what-is-quickshell-in-omarchy)

Discover Quickshell, Omarchy's Wayland compositor and plugin host. Learn how it powers the graphical environment with modular UI components for a seamless desktop experience.

- Tags: deep-dive
- Published: 2026-08-23

### [How to Install Omarchy: Complete Guide for Full-Disk and Dual-Boot Setups](/basecamp/omarchy/how-to-install-omarchy)

Install Omarchy easily with our complete guide. Automate partitioning encryption and bootloader setup for full-disk or dual-boot systems.

- Tags: how-to-guide
- Published: 2026-08-23

### [What Is the `omarchy update` Command For? Complete System Update Workflow](/basecamp/omarchy/what-is-the-omarchy-update-command-for)

Master the omarchy update command for safe, atomic system-wide updates. Refresh Omarchy and Arch Linux packages with snapshots locks and cleanup.

- Tags: how-to-guide
- Published: 2026-08-22

### [How to Use Placeholders in Omarchy Theme Templates](/basecamp/omarchy/how-do-i-use-placeholders-in-omarchy-theme-templates)

Learn how to use {{ variable }} placeholders in Omarchy theme templates to customize your configuration files using colors.toml and the omarchy-refresh-config command.

- Tags: how-to-guide
- Published: 2026-08-22

### [Understanding colors.toml in Omarchy Theming: The Centralized Palette System](/basecamp/omarchy/what-is-the-purpose-of-colortoml-in-omarchy-theming)

Discover how Omarchy's colors.toml acts as a centralized palette system, defining named colors for consistent desktop environment visuals. Learn about this key theming file.

- Tags: internals
- Published: 2026-08-22

### [How User Themes Overlay Built-In Omarchy Themes: Complete Technical Guide](/basecamp/omarchy/how-are-user-themes-overlaid-on-top-of-built-in-omarchy-themes)

Discover how Omarchy applies user themes by overriding built-in defaults. This guide explains the `~/.config/omarchy/theme/` file replacement process.

- Tags: deep-dive
- Published: 2026-08-22

### [How the omarchy-theme-set Command Activates a Theme Across Omarchy](/basecamp/omarchy/how-does-the-omarchy-theme-set-command-activate-a-theme)

Learn how the omarchy-theme-set command activates a theme by locking files, rendering templates, running update scripts, and firing a theme-set hook for full desktop synchronization.

- Tags: how-to-guide
- Published: 2026-08-22

### [Where Are Omarchy Themes Stored? A Complete Guide to Theme Locations and Management](/basecamp/omarchy/where-are-omarchy-themes-stored)

Discover where Omarchy themes are stored. Learn about stock and custom theme locations, `/usr/share/omarchy/themes/` and `~/.config/omarchy/themes/`, for efficient management.

- Tags: how-to-guide
- Published: 2026-08-22

### [How to Define Custom Bar Widgets Inline in Omarchy](/basecamp/omarchy/can-i-define-custom-bar-widgets-inline-in-omarchy)

Learn how to define custom bar widgets in Omarchy. While inline configuration is possible for existing settings, new widget logic requires a separate Lua plugin file.

- Tags: how-to-guide
- Published: 2026-08-22

### [How to Configure the Bar Layout in Omarchy Quickshell: A Complete Guide](/basecamp/omarchy/how-do-i-configure-the-bar-layout-in-omarchys-quickshell)

Learn to configure the bar layout in Omarchy Quickshell. Master widget positioning using shell.json for a personalized terminal experience. Full guide and CLI tips included.

- Tags: how-to-guide
- Published: 2026-08-22

### [How Quickshell Plugins Are Sandboxed in Omarchy: Filesystem Security Explained](/basecamp/omarchy/how-are-quickshell-plugins-sandboxed-in-omarchy)

Discover how Omarchy sandboxes Quickshell plugins with a robust filesystem security model. Learn about the PluginRegistry and path validation techniques.

- Tags: internals
- Published: 2026-08-22

### [What Are the Different Kinds of Quickshell Plugins in Omarchy?](/basecamp/omarchy/what-are-the-different-kinds-of-quickshell-plugins-in-omarchy)

Discover the six Quickshell plugin kinds in Omarchy: bar, overlay, menu, bar-widget, service, and panel. Learn how each plugin kind loads, persists, or summons components via its manifest.json.

- Tags: deep-dive
- Published: 2026-08-22

### [How to Add a Third-Party Plugin to Omarchy's Quickshell: A Complete Guide](/basecamp/omarchy/how-do-i-add-a-third-party-plugin-to-omarchys-quickshell)

Learn how to add third-party plugins to Omarchy's Quickshell. Easily integrate custom functionality by cloning repos, scanning manifests, and hot-reloading plugins with simple commands.

- Tags: how-to-guide
- Published: 2026-08-22

### [How Omarchy Resolves Command Routes Using Longest‑Prefix Matching](/basecamp/omarchy/how-does-omarchy-resolve-command-routes-using-longest-prefix-matching)

Omarchy resolves command routes using longest-prefix matching by prioritizing exact ID matches over shorter aliases for efficient command resolution. Learn how it works.

- Tags: internals
- Published: 2026-08-22

### [Understanding Omarchy Command Metadata Comments: A Complete Guide](/basecamp/omarchy/what-information-can-be-found-in-omarchy-command-metadata-comments)

Discover Omarchy command metadata comments. Learn how these `# omarchy:` comments in your scripts document commands, define routing, and set privileges for automatic help generation.

- Tags: deep-dive
- Published: 2026-08-22

### [How Omarchy Commands with Metadata Aliases Work: Route Registration and Conflict Resolution](/basecamp/omarchy/how-are-omarchy-commands-with-metadata-aliases-handled)

Learn how Omarchy commands with metadata aliases work. Discover route registration and conflict resolution in Omarchy's CLI router for efficient command mapping.

- Tags: internals
- Published: 2026-08-22

### [What Is the Fast Path in the Omarchy CLI Router?](/basecamp/omarchy/what-is-the-fast-path-in-the-omarchy-cli-router)

Discover the Omarchy CLI router's fast path for constant-time command lookups. Learn how it efficiently matches executables before falling back to flexible parsing.

- Tags: deep-dive
- Published: 2026-08-22

### [How the `bin/omarchy` CLI Router Dispatches Commands: Dynamic Routing in Omarchy](/basecamp/omarchy/how-does-the-bin-omarchy-cli-router-dispatch-commands)

Discover how bin/omarchy dynamically dispatches commands. Explore its two-phase lookup system, route tables, and fast-path binary matching for efficient CLI command resolution.

- Tags: internals
- Published: 2026-08-22

### [How to Reset Your Home Directory to Omarchy Defaults: Complete Guide](/basecamp/omarchy/how-can-i-reset-my-home-directory-to-omarchys-defaults)

Easily reset your home directory to Omarchy defaults. This guide explains how to run the omarchy-refresh-config command, backup existing settings, and restore defaults from the repository.

- Tags: how-to-guide
- Published: 2026-08-22

### [When Is the `omarchy finalize user` Command Executed? A Full Lifecycle Explanation](/basecamp/omarchy/when-is-the-omarchy-finalize-user-command-executed)

Understand when the omarchy finalize user command runs automatically after provisioning and upgrades. Learn manual execution for debugging in the basecamp/omarchy repository.

- Tags: internals
- Published: 2026-08-22

### [What Is the Purpose of the Seed Layer in Omarchy's Home Directory?](/basecamp/omarchy/what-is-the-purpose-of-the-seed-layer-in-omarchys-home-directory)

Discover the purpose of the Seed layer in Omarchy's home directory. This initial phase copies static config files to new user accounts, ensuring a consistent setup.

- Tags: deep-dive
- Published: 2026-08-22

### [How Omarchy Manages User Home Directory Configurations](/basecamp/omarchy/how-does-omarchy-manage-user-home-directory-configurations)

Discover how Omarchy manages user home directory configurations. Learn how omarchy-refresh-config syncs defaults, backs up existing files, and validates paths for a consistent project state.

- Tags: how-to-guide
- Published: 2026-08-22

### [What Does the Omarchy-Settings Package Include? A Complete Component Guide](/basecamp/omarchy/what-does-the-omarchy-settings-package-include)

Explore the omarchy-settings package! Discover configuration files, theme definitions, menu schemas, Quickshell UI, migrations, and CLI tools for managing your Omarchy desktop environment.

- Tags: component-guide
- Published: 2026-08-22

### [Where Are Omarchy Runtime Binaries and Scripts Located?](/basecamp/omarchy/where-are-omarchys-runtime-binaries-and-scripts-located)

Find Omarchy runtime binaries and scripts easily. Discover the bin/omarchy and bin/omarchy-* locations for core functions and shell/ for UI scripts in the basecamp/omarchy repository.

- Tags: how-to-guide
- Published: 2026-08-22

### [How Omarchy Is Installed on Arch Linux: Complete Installation Pipeline](/basecamp/omarchy/how-is-omarchy-installed-on-arch-linux)

Install Omarchy on Arch Linux with our automated Bash wizard. This full-stack ISO simplifies partitioning, encryption, and configuration in seven easy steps. Get started now.

- Tags: how-to-guide
- Published: 2026-08-22

### [How Surface Roles and Sizing Are Defined in Omarchy Themes](/basecamp/omarchy/how-are-surface-roles-and-sizing-defined-in-omarchy-themes)

Learn how Omarchy themes define surface roles and sizing with clear separation of concerns using shell.toml and colors.toml for efficient UI theming.

- Tags: how-to-guide
- Published: 2026-08-21

### [Omarchy Color Tokens: Complete Reference for Theme Customization](/basecamp/omarchy/what-color-tokens-are-available-in-omarchy-themes)

Explore the Omarchy color tokens and customize your themes. Discover background, foreground, accent, and ANSI colors for consistent styling in Hyprland, BTOP, and Neovim.

- Tags: api-reference
- Published: 2026-08-21

### [What Files Define a Theme in Omarchy? A Complete Technical Guide](/basecamp/omarchy/what-files-define-a-theme-in-omarchy)

Discover the Omarchy files defining themes: TOML palette files and default themed template files. Learn how they interpolate RGBA hex color values for configurations. Get the complete technical guide.

- Tags: how-to-guide
- Published: 2026-08-21

### [How Theming Is Managed in Omarchy](/basecamp/omarchy/how-is-theming-managed-in-omarchy)

Discover how Omarchy manages theming using a decoupled architecture. Learn about TOML color definitions, QML templates, and CLI commands for active desktop configuration.

- Tags: internals
- Published: 2026-08-21

### [How to Configure Idle Timers for Screensaver and Lock in Omarchy](/basecamp/omarchy/how-to-configure-idle-timers-for-screensaver-and-lock-in-omarchy)

Learn how to configure idle timers for screensaver and lock in Omarchy. Easily adjust settings in shell.json or use the omarchy toggle CLI for custom idle durations.

- Tags: how-to-guide
- Published: 2026-08-21

### [How to Customize the Omarchy Bar Layout: A Complete Guide to Panel and Widget Configuration](/basecamp/omarchy/how-to-customize-the-omarchy-bar-layout)

Learn how to customize the Omarchy bar layout by editing the groupbar table in looknfeel.lua. This guide covers panel ordering and widget assignments for a personalized setup.

- Tags: how-to-guide
- Published: 2026-08-21

### [Where Is the Omarchy Shell Configuration Stored? A Complete Guide to Config Paths](/basecamp/omarchy/where-is-omarchy-shell-configuration-stored)

Find where Omarchy shell configuration is stored. Learn about user-specific and default config paths for easy management and customization.

- Tags: how-to-guide
- Published: 2026-08-21

### [How to Enable or Disable Plugins in Omarchy Using IPC](/basecamp/omarchy/how-to-enable-or-disable-plugins-in-omarchy-using-ipc)

Learn how to enable or disable Omarchy plugins easily using IPC. Control your plugins instantly with simple commands via the omarchy-shell CLI for a seamless workflow.

- Tags: how-to-guide
- Published: 2026-08-21

### [How Plugins Work in the Omarchy Quickshell Desktop: Architecture and Implementation](/basecamp/omarchy/how-do-plugins-work-in-the-omarchy-quickshell-desktop)

Explore how Omarchy Quickshell desktop plugins work. Learn about its file-based system, JSON manifests, registry components, and configuration for seamless extension management.

- Tags: architecture
- Published: 2026-08-21

### [How the Omarchy Desktop Environment Is Structured: A Deep Dive into the Quickshell Architecture](/basecamp/omarchy/how-is-the-omarchy-desktop-environment-structured)

Explore the Omarchy desktop environment's Quickshell architecture. Learn how modular plugins and RPC calls structure this single long-running process for seamless operation.

- Tags: deep-dive
- Published: 2026-08-21

### [What is Quickshell in the Context of Omarchy: Desktop Construction Kit Explained](/basecamp/omarchy/what-is-quickshell-in-the-context-of-omarchy)

Discover Quickshell, the core desktop construction kit powering Omarchy. Learn how this Wayland compositor hosts UI components as modular JavaScript/QML plugins.

- Tags: deep-dive
- Published: 2026-08-21

### [How to Check for Command Alias and Route Collisions in the Omarchy CLI](/basecamp/omarchy/how-to-check-for-command-alias-and-route-collisions-in-omarchy-cli)

Prevent command alias and route collisions in Omarchy CLI by inspecting metadata with `omarchy commands --json` and running `./test/cli` to validate.

- Tags: how-to-guide
- Published: 2026-08-21

### [How the Omarchy CLI Dispatch Mechanism Routes Commands: Fast Path vs. Metadata Resolution](/basecamp/omarchy/how-does-the-omarchy-cli-dispatch-mechanism-handle-commands)

Discover how the Omarchy CLI routes commands using its two-stage dispatch mechanism. Learn about fast path binaries and metadata resolution for efficient command handling.

- Tags: internals
- Published: 2026-08-21

### [Omarchy CLI Command Groups: Complete Guide to the Router Architecture](/basecamp/omarchy/what-are-the-different-command-groups-in-omarchy-cli)

Explore Omarchy CLI command groups like toggle capture theme and system. Understand the router architecture and how commands map to verb implementations in this complete guide.

- Tags: deep-dive
- Published: 2026-08-21

### [How Omarchy CLI Commands Are Organized into Groups: The Complete Guide](/basecamp/omarchy/how-are-omarchy-cli-commands-organized-into-groups)

Learn how Omarchy CLI commands organize into groups using a deterministic naming convention like omarchy-<group>-<verb>. Discover the complete guide to Omarchy command organization.

- Tags: how-to-guide
- Published: 2026-08-21

### [Omarchy CLI Command Metadata Format: A Complete Guide to Command Headers](/basecamp/omarchy/what-is-the-metadata-format-for-omarchy-cli-commands)

Master the Omarchy CLI command metadata format. Learn how structured comment headers define routing, documentation, and execution behavior for your commands. Read the complete guide.

- Tags: api-reference
- Published: 2026-08-21

### [How Omarchy CLI Command Discovery Works: A Deep Dive into the Self-Discovering Router](/basecamp/omarchy/how-does-the-omarchy-cli-command-discovery-work)

Discover how Omarchy CLI command discovery automatically scans bin/ for commands, extracts metadata from comments, and routes execution with longest-prefix matching.

- Tags: deep-dive
- Published: 2026-08-21

### [Omarchy Package Split Documentation: Location and File Reference Guide](/basecamp/omarchy/where-can-i-find-the-omarchy-package-split-documentation)

Locate the Omarchy package split documentation at docs/package-split.md on the quattro branch of the basecamp/omarchy repository. Find detailed implementation guides for CLI router agents and tiling.

- Tags: api-reference
- Published: 2026-08-21

### [What Are the Two Main Packages in Omarchy?](/basecamp/omarchy/what-are-the-two-main-packages-in-omarchy)

Discover the two main packages in Omarchy: omarchy (stable) and omarchy-dev (edge). Understand how they provide a complete desktop environment via distinct release channels.

- Tags: getting-started
- Published: 2026-08-21

### [What Is the Base of Omarchy Linux? Arch Foundation Explained](/basecamp/omarchy/what-is-the-base-of-omarchy-linux)

Discover Omarchy Linux's foundation: built on Arch Linux. Explore its rolling release, pacman package manager, and curated Hyprland desktop.

- Tags: deep-dive
- Published: 2026-08-21

### [How to Install the Omarchy Linux Distribution: Complete Setup Guide](/basecamp/omarchy/how-to-install-omarchy-linux-distribution)

Install Omarchy Linux easily with our guide. Learn about guided installation modes, LUKS encryption, and automated post-install setup for a seamless experience.

- Tags: getting-started
- Published: 2026-08-21

### [How omarchy-dev-link Enables Development Against a Local Checkout](/basecamp/omarchy/how-does-omarchy-dev-link-enable-development-against-a-checkout)

Learn how omarchy-dev-link helps you develop against a local Omarchy checkout. This tool redirects your installation to use local source, streamlining your workflow.

- Tags: how-to-guide
- Published: 2026-08-20

### [How `omarchy-reinstall-configs` Works with `/etc/skel` Seeding and Resync](/basecamp/omarchy/how-does-omarchy-reinstall-configs-work-with-etkskel-seeding-and-resync)

Learn how omarchy-reinstall-configs resets user configs using /etc/skel. Discover how it seeds and resyncs your home directory to factory defaults.

- Tags: internals
- Published: 2026-08-20

### [Omarchy First-Run Provisioning Workflow: How It Automates User Setup on Initial Login](/basecamp/omarchy/what-is-the-omarchy-first-run-provisioning-workflow)

Discover the Omarchy first-run provisioning workflow. Automate user setup on first login, enabling systemd units, themes, and more with this idempotent script.

- Tags: how-to-guide
- Published: 2026-08-20

### [How Omarchy Uses systemd User Services for Per-User Daemon Management](/basecamp/omarchy/how-are-systemd-user-services-managed-for-per-user-daemons-in-omarchy)

Learn how Omarchy manages per-user daemons using systemd user services. Discover their approach to unit file deployment and service enablement for efficient background process control.

- Tags: how-to-guide
- Published: 2026-08-20

### [Omarchy Sudo vs Pkexec: How It Chooses Privilege Escalation Based on Terminal Context](/basecamp/omarchy/how-does-omarchy-choose-between-sudo-and-pkexec-for-privilege-escalation)

Learn how Omarchy chooses between sudo and pkexec for privilege escalation based on terminal availability. Discover its terminal-detection heuristic for seamless CLI and GUI operations.

- Tags: deep-dive
- Published: 2026-08-20

### [How the Hyprland Theme Template Generates Configuration in Basecamp/Omarchy](/basecamp/omarchy/how-does-the-hyprland-theme-template-generate-configuration)

Learn how the Hyprland theme template in Basecamp/Omarchy generates its configuration. Discover its Quickshell rendering pipeline and colors.toml integration.

- Tags: how-to-guide
- Published: 2026-08-20

### [How Omarchy Seeds New User Environments Using `/etc/skel`](/basecamp/omarchy/how-does-omarchy-seed-new-user-environments-with-etkskel)

Discover how Omarchy leverages /etc/skel to seed new user environments with essential dotfiles and configurations for a seamless setup.

- Tags: how-to-guide
- Published: 2026-08-20

### [How Omarchy Maps Repository Sources to Installed Packages: A Deep Dive Into Its Package Mapping System](/basecamp/omarchy/how-does-omarchy-map-repository-sources-to-installed-packages)

Discover how Omarchy maps repository sources to installed packages using its data-driven associative array for modular, manifest-based system installation.

- Tags: deep-dive
- Published: 2026-08-20

### [How Omarchy Performs Acceptance Tests and Visual Verification: A Complete Guide](/basecamp/omarchy/how-does-omarchy-perform-acceptance-tests-and-visual-verification)

Learn how Omarchy uses automated graphical acceptance tests and manual visual verification with screenshots and recordings to ensure code quality. Discover Omarchy's two-layer quality gate.

- Tags: how-to-guide
- Published: 2026-08-20

### [What Are Omarchy's CLI Tests and Shell Tests? A Complete Guide to the Testing Architecture](/basecamp/omarchy/what-are-omarchys-cli-tests-and-shell-tests)

Explore Omarchy's testing architecture. Understand CLI tests for command-line validation and shell tests for Quickshell desktop environment verification in this complete guide.

- Tags: how-to-guide
- Published: 2026-08-20

### [How Omarchy's Test Suite Structure Works: A Complete Guide to CLI, Shell, and Acceptance Testing](/basecamp/omarchy/how-does-omarchys-test-suite-structure-work)

Explore Omarchy's test suite structure. Learn how CLI, shell, and acceptance tests are organized and executed for efficient development and quality assurance.

- Tags: deep-dive
- Published: 2026-08-20

### [How CLI Command Metadata Comments Like # omarchy:hidden Affect Routing in Omarchy](/basecamp/omarchy/how-do-cli-command-metadata-comments-like-omarchyhidden-affect-routing)

Learn how # omarchy:hidden metadata comments impact Omarchy routing. Discover how to hide commands from listings while ensuring normal direct invocation.

- Tags: internals
- Published: 2026-08-20

### [Understanding Omarchy's Menu Guards and Providers: A Deep Dive into Dynamic Desktop Menus](/basecamp/omarchy/what-are-omarchys-menu-guards-and-providers)

Explore Omarchy's menu guards and providers. Learn how guards conditionally control menu entries and providers dynamically populate submenus at runtime for advanced desktop menu customization.

- Tags: deep-dive
- Published: 2026-08-20

### [How JSONC Format Powers Omarchy's Menu System: A Deep Dive into Configuration-Driven UI](/basecamp/omarchy/how-does-jsonc-format-play-a-role-in-omarchys-menu-system)

Discover how Omarchy leverages JSONC format for its menu system, allowing declarative customization without code changes. Explore configuration driven UI.

- Tags: deep-dive
- Published: 2026-08-20

### [Omarchy Menu System Architecture: How the Quickshell-Based UI Works](/basecamp/omarchy/what-is-the-architecture-of-omarchys-menu-system)

Explore the Omarchy menu system architecture. Discover how Quickshell powers a data-driven UI with JSONC, a JavaScript runtime, and dynamic providers for a hot-reloadable desktop menu.

- Tags: architecture
- Published: 2026-08-20

### [Omarchy Theme Template Placeholders: Complete Guide to {{ accent }} and All Color Variables](/basecamp/omarchy/what-are-the-template-placeholders-used-in-omarchy-themes-like-accent)

Discover Omarchy theme template placeholders like {{ accent }} and color variables. Learn how these are substituted with hex colors from colors.toml for custom theme building.

- Tags: deep-dive
- Published: 2026-08-20

### [How Omarchy Themes Use `colors.toml` for Customization: A Complete Guide](/basecamp/omarchy/how-do-omarchy-themes-utilize-colorstoml-for-customization)

Learn how Omarchy themes use colors.toml for complete UI customization. This guide explains leveraging the single colors.toml file to define your entire color palette.

- Tags: how-to-guide
- Published: 2026-08-20

### [How Omarchy's Per-User Migration System Handles Version Upgrades](/basecamp/omarchy/how-does-omarchys-per-user-migration-system-handle-version-upgrades)

Discover how Omarchy's per-user migration system simplifies version upgrades. Learn about timestamped scripts and pending changes for seamless updates.

- Tags: internals
- Published: 2026-08-20

### [How Omarchy's `env-bootstrap` Mechanism Prepares Your Shell Environment](/basecamp/omarchy/how-does-omarchys-env-bootstrap-mechanism-work)

Learn how Omarchy's env-bootstrap script prepares your shell environment by setting OMARCHY_PATH and creating an ordered PATH before commands run.

- Tags: internals
- Published: 2026-08-20

### [What Is the OMARCHY_PATH Environment Variable in Omarchy?](/basecamp/omarchy/what-is-the-purpose-of-the-omarchy_path-environment-variable-in-omarchy)

Understand the OMARCHY_PATH environment variable in Omarchy. Learn how it defines the installation root for scripts, runtime, and services, ensuring a unified Omarchy stack.

- Tags: how-to-guide
- Published: 2026-08-20

### [How Omarchy CLI Commands Are Documented with Metadata Comments: A Complete Guide](/basecamp/omarchy/how-are-omarchy-cli-commands-documented-with-metadata-comments)

Learn how Omarchy CLI commands use metadata comments prefixed with # omarchy: for automatic help output generation. A complete guide for developers.

- Tags: how-to-guide
- Published: 2026-08-20

### [How Omarchy's CLI Router Uses Longest-Prefix Matching for Command Dispatch](/basecamp/omarchy/how-does-omarchys-cli-router-use-longest-prefix-matching)

Discover how Omarchy's CLI router uses longest-prefix matching with Bash associative arrays to efficiently dispatch commands to the correct sub-command scripts.

- Tags: internals
- Published: 2026-08-20

### [How Omarchy Manages User Services like bt-agent and omarchy-sleep-lock](/basecamp/omarchy/how-omarchy-manages-user-services-bt-agent-sleep-lock)

Learn how Omarchy manages user services like bt-agent and omarchy-sleep-lock using systemd user units and migration scripts for seamless operation and updates.

- Tags: how-to-guide
- Published: 2026-08-19

### [How Bar Widgets Are Implemented and Configured in Omarchy's shell.json](/basecamp/omarchy/how-omarchy-bar-widgets-implemented-configured-shell-json)

Discover how to implement and configure bar widgets in Omarchy using shell.json. Learn about the manifest-driven registry system and declarative configuration for widget placement and options.

- Tags: how-to-guide
- Published: 2026-08-19

### [How the Omarchy Resync Command Resets User Configurations to Shipped Defaults](/basecamp/omarchy/how-omarchy-resync-command-resets-configs)

Learn how the Omarchy resync command resets user configurations to shipped defaults by overwriting dotfiles with /etc/skel and refreshing themes. Discover the process now.

- Tags: how-to-guide
- Published: 2026-08-19

### [First-Run Setup vs User Finalization in Omarchy: Key Differences Explained](/basecamp/omarchy/differences-between-omarchy-first-run-setup-and-user-finalization)

Understand the key differences between Omarchy's first run setup and user finalization. Learn how each process optimizes your initial experience and runtime environment.

- Tags: deep-dive
- Published: 2026-08-19

### [Omarchy User Provisioning Workflow: Creating Users and Finalizing Setup](/basecamp/omarchy/omarchy-user-provisioning-workflow-create-finalize-users)

Discover the Omarchy user provisioning workflow for automated user creation and system personalization. Learn the three phases: deferred first-boot, runtime finalization, and graphical setup. Automate your setup process.

- Tags: how-to-guide
- Published: 2026-08-19

### [How Omarchy Hooks Function Across pre-refresh, post-update, and Other Event Directories](/basecamp/omarchy/how-omarchy-hooks-function-across-directories)

Understand how Omarchy hooks execute across pre-refresh, post-update, and event directories. Learn its script and directory processing order for efficient event handling.

- Tags: internals
- Published: 2026-08-19

### [How Visual Verification Works for UI Changes in the Omarchy Development Workflow](/basecamp/omarchy/omarchy-development-workflow-visual-verification-ui-changes)

Learn how Omarchy's visual verification ensures UI changes are flawless. Capture and compare screenshots or videos to catch regressions before committing code.

- Tags: how-to-guide
- Published: 2026-08-19

### [How Test Suites Are Organized Within the Omarchy Repository](/basecamp/omarchy/how-omarchy-test-suites-are-organized)

Discover how Omarchy organizes its test suites for efficient development. Learn about CLI, shell integration, and acceptance tests coordinated by the aggregate runner.

- Tags: internals
- Published: 2026-08-19

### [Omarchy Config Refresh Pattern: Defaults, Backups, and Idempotent Updates](/basecamp/omarchy/omarchy-config-refresh-pattern-defaults-backups)

Discover Omarchy's config refresh pattern for seamless user config updates. Safely sync files with defaults, create backups, and view diffs using omarchy-refresh-config.

- Tags: how-to-guide
- Published: 2026-08-19

### [How the Omarchy Menu System Defines Entries and Providers in `omarchy-menu.jsonc`](/basecamp/omarchy/how-omarchy-menu-system-defines-entries-and-providers)

Discover how the Omarchy menu system defines entries and providers in omarchy-menu.jsonc. Learn about static commands, conditional guards, and dynamic JavaScript provider functions for generating submenus.

- Tags: internals
- Published: 2026-08-19

### [How Omarchy Privileged Commands Handle Sudo vs Pkexec Escalation](/basecamp/omarchy/how-omarchy-privileged-commands-handle-sudo-pkexec)

Discover how Omarchy handles privileged commands using sudo vs pkexec for seamless escalation. Learn its smart approach to terminal and non-terminal environments.

- Tags: how-to-guide
- Published: 2026-08-19

### [How the OMARCHY_PATH Environment Variable Is Set and Used at Runtime in Omarchy](/basecamp/omarchy/how-omarchy-path-environment-variable-is-set-and-used)

Discover how the OMARCHY_PATH environment variable is set during login and used by scripts, QML, and systemd to find Omarchy files. Learn its crucial role in the runtime environment.

- Tags: internals
- Published: 2026-08-19

### [How Omarchy Parses Command Metadata: Understanding `#omarchy:summary` and `#omarchy:hidden`](/basecamp/omarchy/how-omarchy-command-metadata-is-parsed)

Learn how Omarchy parses command metadata like #omarchy:summary and #omarchy:hidden. Discover how it controls visibility documentation and behavior by scanning script comments.

- Tags: internals
- Published: 2026-08-19

### [How to Develop and Install Third-Party Plugins for Omarchy Shell](/basecamp/omarchy/develop-and-install-third-party-omarchy-shell-plugins)

Learn how to develop and install third-party plugins for Omarchy Shell. Discover automatic hot-reloading and QML asset integration for seamless plugin development.

- Tags: how-to-guide
- Published: 2026-08-19

### [How Shell Theme Tokens (Color, Style, Border) Work in Omarchy QML](/basecamp/omarchy/how-shell-theme-tokens-work-in-qml-omarchy)

Discover how Omarchy QML's Color Style and Border theme tokens enable automatic visual updates from TOML configuration simplifying UI theming without hardcoding.

- Tags: internals
- Published: 2026-08-19

### [Omarchy File Organization Structure: Complete Directory Layout Guide](/basecamp/omarchy/omarchy-file-organization-and-installation-locations)

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

- Tags: how-to-guide
- Published: 2026-08-19

### [How Omarchy Migrations Work and How to Write New Migration Scripts](/basecamp/omarchy/how-omarchy-migrations-work-and-write-new-scripts)

Learn how Omarchy migrations work and write new migration scripts. Understand one-time repair scripts for package updates and state adjustments.

- Tags: how-to-guide
- Published: 2026-08-19

### [How the Omarchy Theming System Generates Templates and Applies Theme Tokens](/basecamp/omarchy/how-omarchy-theming-system-generates-templates-and-applies-tokens)

Explore how Omarchy's theming system generates templates and applies theme tokens. Learn about template rendering and theme activation for seamless shell customization.

- Tags: internals
- Published: 2026-08-19

### [Quickshell Desktop Shell in Omarchy: Architecture and Plugin Ecosystem](/basecamp/omarchy/what-is-quickshell-desktop-shell-and-supported-plugins)

Discover the Quickshell desktop shell in Omarchy. Learn about its registry-based architecture supporting widgets, overlays, services, and menus, and explore its plugin ecosystem.

- Tags: architecture
- Published: 2026-08-19

### [How the Omarchy CLI Router Resolves Commands and Handles Dispatch](/basecamp/omarchy/how-omarchy-cli-router-resolves-commands-and-dispatches)

Discover how the Omarchy CLI router resolves commands and dispatches with its dynamic scanning, metadata parsing, and efficient two-phase lookup strategy for faster execution.

- Tags: internals
- Published: 2026-08-19

### [Omarchy Roadmap: Planned Features and Architecture Improvements](/basecamp/omarchy/what-is-the-roadmap-for-oarchy)

Explore the Omarchy roadmap and discover upcoming features like automatic pacnew handling and improved pacman guard policies. See architecture improvements for a more robust system.

- Tags: architecture
- Published: 2026-08-19

### [How to Troubleshoot Omarchy Issues: A Complete Diagnostic Guide](/basecamp/omarchy/how-to-troubleshoot-oarchy-issues)

Troubleshoot Omarchy issues effectively with our diagnostic guide. Learn to generate logs, reinstall settings, and restart services for smooth operation. Fix problems fast.

- Tags: how-to-guide
- Published: 2026-08-19

### [API Endpoints for Omarchy: External Service Integration Guide](/basecamp/omarchy/what-are-the-api-endpoints-for-oarchy)

Explore Omarchy's API endpoints for integrating external services like AI agents, weather, and VPN. Learn how this desktop environment connects via shell scripts and QML plugins.

- Tags: api-reference
- Published: 2026-08-19

### [How to Deploy Omarchy on Arch Linux: Complete Installation Guide](/basecamp/omarchy/how-to-deploy-oarchy)

Deploy Omarchy on Arch Linux with this complete guide. Automate package installation, hardware detection, and service configuration by cloning the quattro branch and running the install script.

- Tags: how-to-guide
- Published: 2026-08-19

### [Omarchy Testing Strategies: Shell, CLI, and Acceptance Testing Explained](/basecamp/omarchy/what-are-the-testing-strategies-for-oarchy)

Explore Omarchy testing strategies: shell, CLI, and acceptance tests. Learn how this framework ensures robust software with integrated tests for reliable performance. Read the guide now.

- Tags: testing-strategies
- Published: 2026-08-19

### [Dependencies for Omarchy: Core System Requirements and Package Architecture](/basecamp/omarchy/what-are-the-dependencies-for-oarchy)

Discover Omarchy dependencies: Arch Linux pacman, systemd, bash, git, curl, jq, and hardware specific packages. Learn about its package architecture and core system requirements.

- Tags: internals
- Published: 2026-08-19

### [How to Set Up a Development Environment for Omarchy: Complete Developer Guide](/basecamp/omarchy/how-to-set-up-a-development-environment-for-oarchy)

Set up your Omarchy development environment quickly. Link your system to local Git for live updates and testing. Get the complete developer guide now.

- Tags: how-to-guide
- Published: 2026-08-19

### [What is the License for Omarchy? MIT License Terms and Verification Guide](/basecamp/omarchy/what-is-the-license-for-oarchy)

Discover the MIT License terms for Omarchy. Understand its permissive use for commercial projects, modification, and distribution. Verify your compliance easily.

- Tags: getting-started
- Published: 2026-08-19

### [How to Contribute to the Omarchy Project: A Complete Developer's Guide](/basecamp/omarchy/how-to-contribute-to-the-oarchy-project)

Learn how to contribute to the Omarchy project. Fork the repo, run tests, follow commit conventions, and submit pull requests with visual verification for UI changes.

- Tags: how-to-guide
- Published: 2026-08-19

### [Development Guidelines for Omarchy: Contributing to the Arch-Based Desktop Environment](/basecamp/omarchy/what-are-the-development-guidelines-for-oarchy)

Contribute to Omarchy, an Arch-based desktop environment. Follow development guidelines for repository layout, Bash scripting, migration standards, and testing. Explore the Omarchy repo today.

- Tags: how-to-guide
- Published: 2026-08-19

### [How to Run Omarchy Locally: Complete Setup Guide for Arch Linux](/basecamp/omarchy/how-to-run-oarchy-locally)

Learn how to run Omarchy locally on Arch Linux. Follow this guide to clone the repository, install, configure, and launch the Omarchy UI with simple commands.

- Tags: how-to-guide
- Published: 2026-08-19

### [Configuration Options for Omarchy: A Complete Guide to Customizing Your Desktop Environment](/basecamp/omarchy/what-are-the-available-configuration-options-for-oarchy)

Explore Omarchy configuration options to customize your desktop environment. Learn to modify layouts, plugins, menus, and themes with JSON and TOML files.

- Tags: how-to-guide
- Published: 2026-08-19

### [How to Configure Omarchy: Complete Guide to Shell, Themes, and Plugins](/basecamp/omarchy/how-to-configure-oarchy)

Easily configure Omarchy with this complete guide. Customize shell layout, apply themes, and manage plugins to personalize your Omarchy experience.

- Tags: how-to-guide
- Published: 2026-08-19

### [What Database Does Omarchy Use?](/basecamp/omarchy/what-database-does-oarchy-use)

Omarchy uses a local SQLite database named opencode.db for AI agent data. Learn where Oarchy stores its persistent data and understand its simple database setup.

- Tags: deep-dive
- Published: 2026-08-19

### [How Omarchy Handles User Authentication: PAM, Polkit, and Hardware Security](/basecamp/omarchy/how-does-oarchy-handle-user-authentication)

Discover how Omarchy secures user authentication using Linux PAM, Polkit, and hardware security keys like FIDO2 for passwords, fingerprints, and sudo access.

- Tags: deep-dive
- Published: 2026-08-19

### [Core Components of Omarchy: The Modular Desktop Environment Explained](/basecamp/omarchy/what-are-the-core-components-of-oarchy)

Explore Omarchy's core components like the Quickshell runtime, CLI tools, plugin system, and theming. Understand how these elements create a script-driven, extensible desktop environment.

- Tags: deep-dive
- Published: 2026-08-19

### [How Omarchy Is Structured: The Two-Package Architecture Explained](/basecamp/omarchy/how-is-oarchy-structured)

Discover Omarchy's two package architecture. Learn how it separates runtime binaries from system defaults, deploying three layers to populate user home directories for efficient system management.

- Tags: architecture
- Published: 2026-08-19

### [Where to Find the Omarchy Source Code: Complete Guide to the basecamp/omarchy Repository](/basecamp/omarchy/where-can-i-find-the-oarchy-source-code)

Find the Omarchy source code in the public basecamp/omarchy GitHub repository. Access the full Linux environment, runtime binaries, scripts, and documentation on the quattro branch.

- Tags: getting-started
- Published: 2026-08-19

### [What Is the Main Purpose of the Omarchy Project?](/basecamp/omarchy/what-is-the-main-purpose-of-the-oarchy-project)

Discover the Omarchy project a modern Arch-based Linux distro offering a complete desktop with Quickshell compositor unified CLI and plugin architecture for a seamless experience.

- Tags: getting-started
- Published: 2026-08-19

### [What Programming Languages Does Omarchy Use? A Complete Technical Breakdown](/basecamp/omarchy/what-programming-languages-does-oarchy-use)

Discover the programming languages Omarchy uses. Explore its multi-language architecture featuring Bash, QML, JavaScript, JSON, and TOML for system scripting, UI, logic, and configuration.

- Tags: deep-dive
- Published: 2026-08-19

### [Prerequisites for Omarchy: Complete Installation Requirements Guide](/basecamp/omarchy/what-are-the-prerequisites-for-oarchy)

Install Omarchy with ease by meeting the key prerequisites: Arch Linux, systemd, pacman, Quickshell, git, and curl. Explore optional components for enhanced functionality.

- Tags: getting-started
- Published: 2026-08-19

### [How to Install Omarchy (Quattro) on Arch Linux: A Complete Guide](/basecamp/omarchy/how-to-install-oarchy)

Install Omarchy Quattro on Arch Linux with our guide. Clone the repository, switch branches, and run the upgrade command for a smooth setup.

- Tags: how-to-guide
- Published: 2026-08-19

### [What is Omarchy? A Deep Dive into Basecamp's Linux Distribution](/basecamp/omarchy/what-is-oarchy)

Discover Omarchy, Basecamp's opinionated Linux distribution. Explore its Bash CLI router, QML Quickshell desktop, and Hyprland for a cohesive, extensible experience.

- Tags: deep-dive
- Published: 2026-08-19

### [How to Set Up Hardware Authentication in Omarchy: Fingerprint and FIDO2 Setup Guide](/basecamp/omarchy/how-set-up-hardware-authentication-omarchy-fingerprint-fido2)

Effortlessly set up hardware authentication in Omarchy with our guide. Learn to configure fingerprint and FIDO2 keys easily. Secure your system now.

- Tags: how-to-guide
- Published: 2026-08-18

### [How Screen Capture and Recording Work in Omarchy: A Technical Deep-Dive](/basecamp/omarchy/how-screen-capture-recording-work-omarchy)

Discover how Omarchy handles screen capture and recording using Wayland tools like slurp and grim. Understand the technical implementation for seamless screen recording.

- Tags: deep-dive
- Published: 2026-08-18

### [How to Configure the Bar Layout in Omarchy: A Complete Guide](/basecamp/omarchy/how-bar-layout-configured-omarchy)

Learn how to configure the bar layout in Omarchy. This guide details using the shell.json file to customize left, center, and right widget sections with plugin descriptors.

- Tags: how-to-guide
- Published: 2026-08-18

### [Omarchy vs omarchy-settings: Understanding the Two-Package Architecture](/basecamp/omarchy/difference-purpose-omarchy-omarchy-settings-packages)

Understand the difference between omarchy and omarchy-settings packages. Discover how this two-package architecture enables clean bootstrapping and independent upgrades for Omarchy.

- Tags: architecture
- Published: 2026-08-18

### [How Omarchy's File Layout Maps to Installed Paths on Arch Linux](/basecamp/omarchy/how-omarchy-file-layout-maps-installed-paths)

Learn how Omarchy's file layout maps to installed paths on Arch Linux. Discover how its two logical packages ensure efficient system integration and configuration.

- Tags: architecture
- Published: 2026-08-18

### [How to Debug Omarchy Issues: A Complete Guide to System Diagnostics and Troubleshooting](/basecamp/omarchy/how-debug-omarchy-issues)

Debug Omarchy issues with `omarchy debug` or `omarchy debug-idle` to capture system snapshots. Upload logs to logs.omarchy.org for maintainer support and fast resolution.

- Tags: how-to-guide
- Published: 2026-08-18

### [Omarchy Privilege Escalation Model: How `sudo` and `pkexec` Work Together](/basecamp/omarchy/what-omarchy-privilege-escalation-model-sudo-pkexec)

Explore the Omarchy privilege escalation model. Discover how sudo and pkexec work together for secure terminal and graphical authentication, ensuring seamless access.

- Tags: internals
- Published: 2026-08-18

### [How User Hooks Automation Works in Omarchy: A Complete Guide to Custom Script Execution](/basecamp/omarchy/how-user-hooks-automation-works-omarchy)

Discover how Omarchy user hooks automation executes custom scripts during user lifecycle events. Learn to automate post-update, theme changes, and package refreshes with this powerful guide.

- Tags: how-to-guide
- Published: 2026-08-18

### [How Omarchy Configures Web App Handlers: A Complete Technical Breakdown](/basecamp/omarchy/how-web-app-handlers-configured-omarchy)

Discover how Omarchy configures web app handlers using XDG desktop entries Bash wrappers and JSON-C menus for seamless install launch and remove workflows. Get the technical breakdown.

- Tags: deep-dive
- Published: 2026-08-18

### [How Omarchy Hardware Detection Commands Work: A Deep Dive into Sysfs-Based Detection](/basecamp/omarchy/how-omarchy-hardware-detection-commands-operate)

Explore how Omarchy hardware detection commands use Bash scripts to interrogate sysfs and DMI data for hardware identification. Discover efficient system analysis.

- Tags: deep-dive
- Published: 2026-08-18

### [How the Omarchy Update System Works: A Deep Dive into the Atomic Upgrade Pipeline](/basecamp/omarchy/what-process-omarchy-update-system)

Explore the Omarchy update system's atomic upgrade pipeline. Learn how exclusive locking, Btrfs snapshots, and ten specialized phases ensure safe system updates for your repository.

- Tags: deep-dive
- Published: 2026-08-18

### [Omarchy Package Management Integration: How It Wraps Pacman for Safe, Testable System Operations](/basecamp/omarchy/how-omarchy-integrates-package-management)

Discover how Omarchy integrates with package management by wrapping pacman commands. Achieve safe, testable system operations with a unified interface for menus, migrations, and updates.

- Tags: how-to-guide
- Published: 2026-08-18

### [How Omarchy-Shell IPC Communication Works: A Deep Dive Into Quickshell Integration](/basecamp/omarchy/how-omarchy-shell-ipc-communication-works)

Discover how Omarchy-shell IPC communication works using Quickshell's Unix-domain sockets. Learn how bash commands connect to QML objects via ipcTarget for seamless integration.

- Tags: deep-dive
- Published: 2026-08-18

### [How Hyprland Configuration is Organized in Omarchy: A Layered Approach Explained](/basecamp/omarchy/how-hyprland-configuration-organized-omarchy)

Discover Omarchy's layered Hyprland configuration: default bootstrap files, theme overrides, and user settings. Keep customizations safe and organized with this robust approach.

- Tags: internals
- Published: 2026-08-18

### [How Themes Are Structured and Applied in Omarchy: A Complete Technical Guide](/basecamp/omarchy/how-themes-structured-applied-omarchy)

Explore Omarchy's directory based theming structure featuring a colors.toml palette and runtime generation pipeline for desktop shell configuration and template rendering.

- Tags: deep-dive
- Published: 2026-08-18

### [Omarchy Refresh Pattern: How to Safely Restore Default Configuration Files](/basecamp/omarchy/what-refresh-pattern-restores-defaults-omarchy)

Safely restore default config files with Omarchy's refresh pattern. It backs up your current settings, applies defaults, and shows changes, protecting your customizations.

- Tags: how-to-guide
- Published: 2026-08-18

### [How Omarchy Handles Migrations: A Technical Guide to Post-Upgrade Configuration Changes](/basecamp/omarchy/how-migrations-handled-in-omarchy)

Discover how Omarchy handles migrations with self-contained Bash scripts and idempotent updates coordinated via Pacman transactions. Learn the technical details of the omarchy-migrate command.

- Tags: how-to-guide
- Published: 2026-08-18

### [How the Omarchy Plugin System Manages Bar Widgets: Architecture & Registration Flow](/basecamp/omarchy/how-omarchy-plugin-system-manages-bar-widgets)

Discover how the Omarchy plugin system manages bar widgets with its three-stage architecture: manifests declare capabilities, PluginRegistry loads components, and BarWidgetRegistry provides a reactive UI catalogue.

- Tags: architecture
- Published: 2026-08-18

### [How Omarchy Shell Plugins Function: Quickshell Plugin System Explained](/basecamp/omarchy/how-omarchy-shell-plugins-function)

Discover how Omarchy shell plugins function as self-contained UI extensions within the Quickshell process. Learn about dynamic loading and IPC control.

- Tags: internals
- Published: 2026-08-18

### [How to Create a Custom Omarchy Command: A Complete Developer Guide](/basecamp/omarchy/how-to-create-custom-omarchy-command)

Learn how to create a custom Omarchy command by following this developer guide. Discover how Omarchy finds and parses commands from your bin directory.

- Tags: how-to-guide
- Published: 2026-08-18

### [How Omarchy's CLI Routing System Works Internally: A Deep Dive into the Dispatcher](/basecamp/omarchy/how-omarchy-cli-routing-works-internally)

Discover how Omarchy's CLI routing system works internally with a deep dive into its two-stage dispatch mechanism. Learn about filename matching and metadata-driven lookups.

- Tags: internals
- Published: 2026-08-18