Where Is the Omarchy Shell Configuration Stored? A Complete Guide to Config Paths

Omarchy stores its shell configuration in ~/.config/omarchy/shell.json for user-specific settings, falling back to $OMARCHY_PATH/config/omarchy/shell.json for default values.

Understanding where Omarchy shell configuration is stored is essential for customizing your desktop environment. In the basecamp/omarchy repository, the shell uses a JSON-based configuration system that separates user preferences from shipped defaults. This guide explains the exact file paths and loading mechanism implemented in the source code.

Default vs. User Configuration Paths

Omarchy implements a two-tier configuration system. The default configuration resides in the repository at $OMARCHY_PATH/config/omarchy/shell.json. When you customize settings, the shell writes to the user configuration path at ~/.config/omarchy/shell.json.

In shell/shell.qml, the code explicitly declares these locations through the defaultsPath and userConfigPath variables. The shell first loads the defaults, then checks for the user file. If ~/.config/omarchy/shell.json exists and parses correctly, it overrides the default values.

Key Configuration Files

The following files define how Omarchy manages shell settings:

• shell/shell.qml: Contains the configuration loading logic with defaultsPath pointing to $OMARCHY_PATH/config/omarchy/shell.json and userConfigPath pointing to $HOME/.config/omarchy/shell.json.

• config/omarchy/shell.json: The shipped default configuration that ships with the repository.

• shell/plugins/bar/README.md: Documents how the bar plugin reads its specific settings from ~/.config/omarchy/shell.json.

• shell/README.md: Provides general documentation on the shell's configuration handling.

How Configuration Loading Works

According to the basecamp/omarchy source code, the shell follows a specific precedence order:

1. Load the defaults from $OMARCHY_PATH/config/omarchy/shell.json
2. Check for $HOME/.config/omarchy/shell.json
3. If the user file exists and is valid JSON, merge it with defaults (user values take precedence)
4. If the user file is missing or corrupt, continue using defaults

This approach ensures that users only need to specify values they want to change, while inheriting sensible defaults for everything else.

Reading and Modifying Configuration

You can interact with the Omarchy shell configuration using standard command-line tools or the Omarchy CLI.

View the current configuration:

jq . "$HOME/.config/omarchy/shell.json"

Reset to shipped defaults:

cp "$OMARCHY_PATH/config/omarchy/shell.json" "$HOME/.config/omarchy/shell.json"

Modify settings using the Omarchy CLI (writes to shell.json):

omarchy bar position top

Summary

• Omarchy uses ~/.config/omarchy/shell.json as the primary user configuration location.
• Default values are stored in $OMARCHY_PATH/config/omarchy/shell.json within the repository.
• The loading logic in shell/shell.qml implements a fallback system: defaults first, then user overrides.
• You can manually edit the JSON file or use the omarchy CLI to modify settings.

Frequently Asked Questions

Where is the main Omarchy shell configuration file located?

The primary configuration file is located at ~/.config/omarchy/shell.json. This file stores your personalized settings and overrides the default configuration shipped with the repository at $OMARCHY_PATH/config/omarchy/shell.json.

How do I reset Omarchy shell settings to defaults?

Copy the default configuration from the repository to your user config directory using cp "$OMARCHY_PATH/config/omarchy/shell.json" "$HOME/.config/omarchy/shell.json". This overwrites your custom settings with the original defaults defined in the source tree.

What happens if the user configuration file is missing or invalid?

If ~/.config/omarchy/shell.json does not exist or contains invalid JSON, Omarchy will continue using the default configuration from $OMARCHY_PATH/config/omarchy/shell.json without throwing errors. The shell gracefully handles missing user files by falling back to defaultsPath as defined in shell/shell.qml.

Can I edit the shell configuration manually?

Yes, you can directly edit ~/.config/omarchy/shell.json using any text editor or JSON processor like jq. However, using the omarchy CLI (e.g., omarchy bar position top) is recommended as it validates input and ensures proper JSON formatting before writing to the configuration file.

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