What Is the Purpose of the `omarchy-settings` Package?

The omarchy-settings package is the central configuration layer for Omarchy, responsible for defining configuration schemas, providing default values, loading and validating user overrides, and exposing a singleton API that other components use to query settings.

The omarchy-settings package abstracts away the complexity of configuration management in the Omarchy desktop environment. According to the Omarchy source code, this package ensures that every component—from panel widgets to window managers—reads from a single, validated, and live-reloadable source of truth.

Core Responsibilities of omarchy-settings

Define the Configuration Schema

The package maintains a JSON-Schema-compatible description of all supported configuration keys, their types, allowed ranges, and documentation. This schema enforces type safety and provides IDE autocomplete for users editing their configuration files.

Key file: [omarchy-settings/src/schema.json](https://github.com/omacom/omarchy/blob/quattro/omarchy-settings/src/schema.json)

Provide Sane Defaults

When users haven't supplied custom values, omarchy-settings supplies complete fallback defaults that keep the desktop environment functional out of the box.

Key file: [omarchy-settings/src/defaults.js](https://github.com/omacom/omarchy/blob/quattro/omarchy-settings/src/defaults.js)

Load and Merge User Configuration

The package reads user configuration from $HOME/.config/omarchy/*.json, validates each file against the schema, and performs a deep merge with defaults to produce the final runtime configuration.

Key file: [omarchy-settings/src/load.js](https://github.com/omacom/omarchy/blob/quattro/omarchy-settings/src/load.js)

Expose a Singleton API

Other Omarchy components import omarchy-settings to query values through a unified interface. This guarantees consistency—no component reads configuration files directly.

Key file: [omarchy-settings/src/index.js](https://github.com/omacom/omarchy/blob/quattro/omarchy-settings/src/index.js)

Support Live Reloading

The package watches user configuration files and re-applies merged settings without requiring a session restart, enabling instant feedback when users tweak their desktop.

Key file: [omarchy-settings/src/watch.js](https://github.com/omacom/omarchy/blob/quattro/omarchy-settings/src/watch.js)

How to Use omarchy-settings in Your Code

Import the package and query configuration values using the provided API:

// Import the package (available via npm as `omarchy-settings`)
import settings from 'omarchy-settings';

// Get a single value
const accent = settings.get('theme.accent');

// Retrieve the whole resolved configuration object
const fullConfig = settings.all();

// Listen for live-reload events
settings.on('change', (changedKeys) => {
  console.log('Settings updated:', changedKeys);
});

// Override a setting programmatically
settings.set('window.opacity', 0.85);

React Component Integration

Here's a typical pattern for consuming omarchy-settings in a Quickshell/React component with live updates:

import { useEffect } from 'react';
import settings from 'omarchy-settings';

export default function Panel() {
  useEffect(() => {
    const updateOpacity = () => {
      const opacity = settings.get('panel.opacity');
      document.getElementById('panel').style.opacity = opacity;
    };
    
    // Initialise and watch for changes
    updateOpacity();
    settings.on('change', updateOpacity);
    
    return () => settings.off('change', updateOpacity);
  }, []);
}

Key Files in omarchy-settings

File	Purpose
[omarchy-settings/package.json](https://github.com/omacom/omarchy/blob/quattro/omarchy-settings/package.json)	Package manifest declaring dependencies and entry point
[omarchy-settings/src/schema.json](https://github.com/omacom/omarchy/blob/quattro/omarchy-settings/src/schema.json)	JSON-Schema definition of all configuration keys
[omarchy-settings/src/defaults.js](https://github.com/omacom/omarchy/blob/quattro/omarchy-settings/src/defaults.js)	Built-in default configuration values
[omarchy-settings/src/load.js](https://github.com/omacom/omarchy/blob/quattro/omarchy-settings/src/load.js)	Config file reading, validation, and merging logic
[omarchy-settings/src/index.js](https://github.com/omacom/omarchy/blob/quattro/omarchy-settings/src/index.js)	Public API surface (get, set, all, event methods)
[omarchy-settings/src/watch.js](https://github.com/omacom/omarchy/blob/quattro/omarchy-settings/src/watch.js)	Filesystem watcher for live configuration reloads

Summary

• omarchy-settings centralizes configuration management for the entire Omarchy desktop environment
• Schema validation prevents malformed configuration from crashing components
• Default value fallbacks ensure the system works without user customization
• Live reloading enables rapid iteration when tuning desktop settings
• Singleton API guarantees all components read from the same configuration state

Frequently Asked Questions

How does omarchy-settings handle invalid user configuration?

The package validates user JSON files against [schema.json](https://github.com/omacom/omarchy/blob/quattro/omarchy-settings/src/schema.json) during the load phase. Invalid keys or type mismatches trigger warnings and fall back to default values, preventing component crashes.

Can I use omarchy-settings outside of Omarchy?

While designed for Omarchy, the package is published as a standalone npm module. You can import it in any Node.js or Electron project, though the schema and defaults are tailored to Omarchy's desktop environment needs.

Where does omarchy-settings look for user configuration files?

The loader scans $HOME/.config/omarchy/*.json (or $XDG_CONFIG_HOME/omarchy/*.json if set). Files are loaded in alphabetical order and deep-merged, with later files overriding earlier ones.

Does omarchy-settings support environment variable overrides?

As implemented in omacom/omarchy, the primary mechanism is JSON file configuration. Environment variable support would typically be layered in [load.js](https://github.com/omacom/omarchy/blob/quattro/omarchy-settings/src/load.js) or by preprocessing in the consuming application.

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