How Feature Toggles Work with the toggle-* Command Prefix in Omarchy

Omarchy implements feature toggles as empty flag files stored in $HOME/.local/state/omarchy/toggles/, where file presence indicates an enabled feature and absence indicates a disabled one, managed entirely through the toggle-* command suite.

The omacom/omarchy repository provides a lightweight, file-based feature toggle architecture that persists state across sessions without requiring databases or complex configuration parsers. This system relies on simple POSIX presence-check semantics that function identically across Bash scripts, QML plugins, and systemd service files.

The Flag-File Architecture

Omarchy’s toggle system abandons traditional key-value configuration in favor of empty marker files whose existence alone encodes binary state. This design prioritizes atomic operations and universal accessibility across different runtime environments.

State Directory Structure

All toggle states reside under a single hierarchy:

$HOME/.local/state/omarchy/toggles/

Individual features are identified by filename. For example, enabling the nightlight feature creates an empty file at ~/.local/state/omarchy/toggles/nightlight, while disabling it removes that file entirely. Hyprland-specific toggles extend this pattern by storing Lua configuration snippets under toggles/hypr/$NAME.lua.

Enable/Disable Semantics

The system operates on strict binary logic:

• Enabled: The flag file exists (contents are ignored).
• Disabled: The flag file does not exist.

This convention allows any component—whether a Bash script, QML property binding, or systemd unit condition—to query state using standard filesystem tests like [[ -f ... ]] or ConditionPathExists.

Core toggle-* Commands

The command-line interface provides thin wrappers around these filesystem operations, ensuring consistent state management across the desktop environment.

General-Purpose Toggle (omarchy-toggle)

Located at bin/omarchy-toggle, this script implements the primary state mutation logic. It accepts a target name as $1 and an optional action as $2 (toggle, on, or off). The internal enable() function creates the flag file using touch, while disable() removes it with rm. When invoked without an explicit action, the command toggles the current state—creating the file if absent or removing it if present.

Query Helper (omarchy-toggle-enabled)

The bin/omarchy-toggle-enabled utility provides idempotent state inspection. It returns exit status 0 (success) if the specified toggle is enabled and a non-zero exit code otherwise. The implementation performs a single filesystem test:

[[ -f "$HOME/.local/state/omarchy/toggles/$1" ]]

This makes it ideal for conditional logic in shell scripts and CI pipelines.

Feature-Specific Wrappers

Omarchy distributes convenience scripts following the omarchy-toggle-<feature> naming convention (e.g., omarchy-toggle-touchpad, omarchy-toggle-input-device). These wrappers invoke the core omarchy-toggle command with preset names, sometimes performing additional side effects such as writing to subdirectories for Hyprland device management.

Hyprland-Specific Toggles

The bin/omarchy-hyprland-toggle command manages dynamic configuration injection for the Hyprland compositor. Rather than creating empty files, it copies Lua source snippets from $OMARCHY_PATH/default/hypr/toggles/ into ~/.local/state/omarchy/toggles/hypr/$NAME.lua. The companion command omarchy-hyprland-toggle-disabled removes these Lua files, allowing runtime toggling of window manager behaviors without restarting the session.

System Integration Points

The flag-file architecture enables broad interoperability across Omarchy’s component stack.

Shell and QML Components

Desktop shell plugins read toggle states directly from the filesystem. For example, shell/plugins/bar/Bar.qml checks for the existence of ~/.local/state/omarchy/toggles/bar-off to conditionally hide the panel. This eliminates the need for IPC mechanisms or D-Bus queries when querying simple feature states.

systemd Service Conditions

Systemd units leverage the same paths using ConditionPathExists directives. The default/systemd/user/omarchy-crash-watch.service file demonstrates this pattern:

ConditionPathExists=!%h/.local/state/omarchy/toggles/crash-capture-off

This declarative rule prevents the crash-watching service from starting when the user has explicitly disabled crash capture via the toggle system.

Hyprland Configuration Snippets

The default/hypr/toggles.lua file defines a dynamic include path that Hyprland evaluates at runtime. When omarchy-hyprland-toggle copies a Lua module into the state directory, Hyprland immediately applies the configuration changes, enabling features like window-no-gaps without requiring a full configuration reload.

Working with Feature Toggles

The following examples demonstrate common operations against the toggle system:

# Toggle a feature (creates file if absent, removes if present)

omarchy-toggle nightlight

# Explicitly enable without toggling

omarchy-toggle nightlight on

# Explicitly disable

omarchy-toggle nightlight off

# Check state in a script

if omarchy-toggle-enabled nightlight; then
    echo "Nightlight is active"
else
    echo "Nightlight is disabled"
fi

# Enable a Hyprland-specific behavior

omarchy-hyprland-toggle window-no-gaps

# Disable the Hyprland behavior

omarchy-hyprland-toggle-disabled window-no-gaps

All commands inherit the same atomic semantics: filesystem creation and deletion operations define state, ensuring consistency even when multiple processes query or modify toggles concurrently.

Summary

• Omarchy stores feature toggles as empty flag files in ~/.local/state/omarchy/toggles/, where presence equals enabled and absence equals disabled.
• The bin/omarchy-toggle script provides general-purpose state management with enable(), disable(), and toggle logic.
• bin/omarchy-toggle-enabled offers a lightweight query mechanism returning shell exit codes based on file existence.
• Hyprland integration uses bin/omarchy-hyprland-toggle to manage Lua configuration snippets in a sub-directory.
• The architecture supports cross-cutting concerns: QML plugins read flags directly, systemd units use ConditionPathExists guards, and migration scripts preserve state across upgrades.

Frequently Asked Questions

How do I check if a specific feature toggle is currently enabled?

Use the omarchy-toggle-enabled helper script followed by the toggle name. This command exits with status 0 if the flag file exists (enabled) and non-zero otherwise, making it suitable for use in if statements and shell conditionals without parsing text output.

What is the difference between omarchy-toggle and omarchy-hyprland-toggle?

bin/omarchy-toggle manages simple empty flag files for binary state, while bin/omarchy-hyprland-toggle specifically handles Lua configuration modules for the Hyprland window manager. The Hyprland variant copies source files from the defaults directory rather than creating empty markers, allowing dynamic injection of configuration code.

Where does Omarchy store feature toggle states persistently?

All toggle states are stored in the user’s state directory at $HOME/.local/state/omarchy/toggles/. Hyprland-specific toggle Lua files reside in the hypr/ subdirectory within that path. This location conforms to the XDG Base Directory Specification and survives across login sessions.

Can I create custom feature toggles for my own scripts?

Yes. Any script can participate in the toggle system by creating or removing files in ~/.local/state/omarchy/toggles/. For example, running touch ~/.local/state/omarchy/toggles/my-custom-feature enables the toggle, which can then be queried by other components using standard filesystem tests or the omarchy-toggle-enabled helper.

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