# Quickshell Plugin manifest.json: Complete Field Reference for Omarchy

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

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: api-reference
- Published: 2026-08-25

---

**Every Quickshell plugin requires a [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) file containing at least the `id`, `name`, `kind`, and `entry` fields to register with the Omarchy runtime.**

The [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/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:

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

```

A production-ready plugin includes comprehensive metadata:

```json
{
  "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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/services/nightlight/manifest.json)
- The Media service registers through [`shell/plugins/services/media/manifest.json`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/services/media/manifest.json)
- The Battery service uses [`shell/plugins/services/battery/manifest.json`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/services/battery/manifest.json)
- UI components like the Bar plugin specify configuration in [`shell/plugins/bar/manifest.json`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/bar/manifest.json)
- The OSD and Menu plugins follow the same structure in [`shell/plugins/osd/manifest.json`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/osd/manifest.json) and [`shell/plugins/menu/manifest.json`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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.