Quickshell Plugin manifest.json: Complete Field Reference for Omarchy

Every Quickshell plugin requires a manifest.json file containing at least the id, name, kind, and entry fields to register with the Omarchy runtime.

The manifest.json file serves as the contract between a Quickshell plugin and the Omarchy desktop environment, defining how the plugin loads, displays, and interacts with the system. Located in each plugin's root directory under ~/.config/omarchy/plugins/, this JSON descriptor tells the Quickshell engine where to find the entry-point QML file and what permissions or dependencies the component requires. Understanding the manifest schema is essential for developers extending Omarchy's functionality with custom bars, panels, services, or widgets.

Required Fields Every manifest.json Must Include

According to the basecamp/omarchy source code, four fields are mandatory for the Quickshell engine to recognize and load a plugin:

id (string)

The id provides a unique, namespaced identifier for the plugin. This value must match the directory name under ~/.config/omarchy/plugins/ and typically follows reverse-domain notation (e.g., omarchy.bar, omarchy.weather). The Quickshell runtime uses this identifier for internal registration and dependency resolution.

name (string)

This human-readable display name appears in UI selectors, configuration menus, and logging output. While the id must be machine-friendly, the name field accepts spaces and descriptive language (e.g., "System Bar", "Weather Panel").

kind (string)

The kind field determines the plugin's role within the Quickshell hierarchy. Valid values include bar, panel, service, popup, widget, and menu. This classification tells Omarchy where to instantiate the component—whether as a persistent desktop bar, a system service running in the background, or a transient popup window.

entry (string)

This specifies the relative path to the plugin's main QML file. The Quickshell engine loads this file first when initializing the plugin. Common patterns include Bar.qml for bar plugins, Service.qml for background services, or Panel.qml for panel components.

Optional Metadata and Configuration Fields

Beyond the required fields, developers can include additional metadata to improve discoverability and security:

description, version, and author

The description field provides a short summary of functionality visible in plugin browsers. The version string supports semantic versioning for upgrade checks, while author credits the creator.

icon Path

The optional icon field points to an image file (PNG or SVG) relative to the plugin directory. Omarchy displays this icon in configuration UIs and plugin managers.

dependencies Array

Plugins requiring other components to load first list them in the dependencies array. For example, a weather panel might declare "dependencies": ["omarchy.network"] to ensure network services initialize before attempting API calls.

permissions Array

The permissions field declares runtime capabilities the plugin requests, such as network, filesystem, or bluetooth. The Quickshell engine may prompt users for approval based on these declarations before activating the plugin.

settings Object

Developers provide default configuration values through the settings object. When a user first enables the plugin, Omarchy copies these defaults into ~/.config/omarchy/plugins/<id>/settings.json, which the plugin can then read and modify at runtime.

Minimal vs. Full-Featured manifest.json Examples

A basic plugin requires only the mandatory fields:

{
  "id": "omarchy.bar",
  "name": "Bar",
  "kind": "bar",
  "entry": "Bar.qml"
}

A production-ready plugin includes comprehensive metadata:

{
  "id": "omarchy.weather",
  "name": "Weather Panel",
  "kind": "panel",
  "description": "Shows current weather and forecast.",
  "version": "1.2.0",
  "author": "Basecamp",
  "entry": "WeatherPanel.qml",
  "icon": "icons/weather.svg",
  "dependencies": ["omarchy.network"],
  "permissions": ["network"],
  "settings": {
    "location": "San Francisco, CA",
    "units": "metric"
  }
}

How Omarchy Parses manifest.json at Runtime

The Quickshell engine automatically discovers and parses manifest.json files when scanning the plugins directory. In the basecamp/omarchy repository, several core plugins demonstrate this pattern in practice:

• The Night Light service defines its manifest at shell/plugins/services/nightlight/manifest.json
• The Media service registers through shell/plugins/services/media/manifest.json
• The Battery service uses shell/plugins/services/battery/manifest.json
• UI components like the Bar plugin specify configuration in shell/plugins/bar/manifest.json
• The OSD and Menu plugins follow the same structure in shell/plugins/osd/manifest.json and shell/plugins/menu/manifest.json respectively

Each of these manifests declares the plugin's id, name, and kind, with the entry QML file referenced via the entry field. The engine reads these descriptors to build the plugin registry before instantiating any QML components.

Summary

• Four mandatory fields: Every manifest.json must include id (unique identifier), name (display name), kind (plugin type), and entry (QML file path).
• Metadata support: Optional fields like description, version, author, and icon improve plugin discoverability in the Omarchy interface.
• Dependency management: The dependencies array ensures plugins load in the correct order, while permissions requests runtime capabilities from the user.
• Default configuration: The settings object initializes user preferences on first launch, stored separately in the plugin's config directory.
• Repository location: Omarchy core plugins in basecamp/omarchy demonstrate these patterns in paths like shell/plugins/services/nightlight/manifest.json.

Frequently Asked Questions

What are the mandatory fields in a Quickshell plugin manifest.json?

Every manifest requires four specific fields: id for the unique plugin identifier, name for the human-readable label, kind for the plugin category (bar, service, panel, etc.), and entry pointing to the main QML file. Omitting any of these prevents the Quickshell engine from registering the plugin.

Where does Omarchy look for plugin manifest files?

The Quickshell runtime scans the ~/.config/omarchy/plugins/ directory, where each subdirectory represents a plugin and must contain a manifest.json file. The directory name must match the id field specified in the manifest for the engine to locate resources correctly.

Can a Quickshell plugin depend on other plugins?

Yes, add the dependency IDs to the dependencies array in your manifest.json. The Quickshell engine ensures all listed plugins initialize before loading your component, preventing runtime errors from missing services or uninitialized global objects.

How do I specify default settings in a plugin manifest?

Define default values in the settings object of your manifest.json. When a user first enables your plugin, Omarchy automatically copies these values into ~/.config/omarchy/plugins/<your-plugin-id>/settings.json, which your QML code can read and modify using standard Qt configuration APIs.

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