# Omarchy Plugin Manifest Schema: Complete Developer Guide

> Understand the Omarchy plugin manifest schema. Learn about schemaVersion, id, kinds, and entryPoints for defining plugin identity and QML files in manifest.json.

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

---

**The Omarchy plugin manifest schema defines a strict JSON contract using a [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) file that specifies `schemaVersion`, unique `id`, `kinds` array, and `entryPoints` mapping to declare plugin identity, supported widget types, and QML entry files.**

Every plugin in the `basecamp/omarchy` repository requires a **manifest.json** file placed at the root of the plugin directory (or alongside a QML widget) to declare its capabilities to the Omarchy shell. This schema enables the shell to validate, install, and load extensions ranging from bar widgets to background panels. Understanding the manifest structure is essential for developers extending the desktop environment with custom QML components.

## Required Manifest Properties

The Omarchy plugin manifest schema enforces six mandatory fields that establish the plugin's identity and entry points. According to the source documentation in [`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md), these properties form the minimum valid contract:

- **schemaVersion**: An integer specifying the manifest format version. The current Omarchy release supports version `1`.
- **id**: A unique, namespaced identifier using reverse-domain notation (e.g., `omarchy.bar` or `myorg.mywidget`). This string must be globally unique across all installed plugins.
- **name**: A human-readable string displayed in UI menus and configuration interfaces.
- **version**: A semantic version string (e.g., `1.0.0`) tracking the plugin's release cycle.
- **kinds**: An array of strings declaring which plugin types the extension implements. Valid entries include `"bar"`, `"bar-widget"`, and `"panel"`. A single manifest may declare multiple kinds.
- **entryPoints**: An object mapping each declared kind to its corresponding QML file path. The shell uses these paths to instantiate the appropriate UI components.

## Optional Configuration Flags

Beyond the required fields, the manifest schema supports optional flags that modify runtime behavior:

- **keepLoaded**: A boolean that, when set to `true`, forces the shell to maintain the plugin process even after its UI is dismissed. This enables background services and persistent state management. Without this flag, the shell unloads the plugin when the user closes its interface.
- **barWidget.allowMultiple**: Available exclusively for plugins declaring the `"bar-widget"` kind, this boolean controls whether users can instantiate multiple copies of the widget simultaneously. Set to `false` to enforce singleton behavior.

## Runtime Injection Fields

While not required in the source [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json), the Omarchy shell injects three internal fields at runtime for loaded plugins:

- **omarchyPath**: The absolute path to the Omarchy installation directory.
- **shell**: Reference to the shell's internal API surface.
- **manifest**: The complete parsed manifest object.

These properties appear in the plugin's runtime environment but should never be included in the static manifest file.

## Plugin Installation and Validation

When a user installs a plugin, the Omarchy shell performs strict validation against the manifest schema. As implemented in the installation logic:

1. The shell parses [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) and verifies the `schemaVersion` compatibility.
2. It checks for ID conflicts; if another plugin already claims the same `id`, the installation aborts immediately.
3. Upon successful validation, the shell copies the plugin directory to `~/.config/omarchy/plugins/<id>/`.

To activate a validated plugin, use the shell's IPC interface:

```bash
omarchy-shell ipc enable-plugin myorg.mywidget

```

## Practical Manifest Examples

### Minimal Third-Party Widget

This example implements a single bar widget with singleton enforcement:

```json
{
  "schemaVersion": 1,
  "id": "myorg.mywidget",
  "name": "My Widget",
  "version": "0.1.0",
  "kinds": ["bar-widget"],
  "entryPoints": {
    "bar-widget": "MyWidget.qml"
  },
  "barWidget": {
    "allowMultiple": false
  }
}

```

### Background Service Panel

This manifest configures a panel that remains loaded for background processing:

```json
{
  "schemaVersion": 1,
  "id": "myorg.myservice",
  "name": "My Service",
  "version": "2.3.1",
  "kinds": ["panel"],
  "entryPoints": {
    "panel": "MyServicePanel.qml"
  },
  "keepLoaded": true
}

```

## Key Source Reference Files

Developers should consult these locations in the `basecamp/omarchy` repository for authoritative schema details:

- [`shell/README.md`](https://github.com/basecamp/omarchy/blob/main/shell/README.md) – Overview of the manifest contract and installation flow validation rules.
- [`shell/plugins/README.md`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/README.md) – Index of first-party plugins demonstrating manifest conventions.
- [`shell/plugins/bar/manifest.json`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/bar/manifest.json) – Concrete implementation of the bar plugin manifest.
- [`default/agents/skills/omarchy/plugins.md`](https://github.com/basecamp/omarchy/blob/main/default/agents/skills/omarchy/plugins.md) – Developer-facing documentation for plugin authors.
- [`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md) – Detailed schema specification and runtime flag documentation under the "Plugin Manifest" section.

## Summary

- The **Omarchy plugin manifest schema** requires a [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) with `schemaVersion` (currently `1`), unique `id`, `name`, `version`, `kinds` array, and `entryPoints` object.
- **Optional flags** include `keepLoaded` for background persistence and `barWidget.allowMultiple` for controlling widget instance count.
- The shell validates manifests during installation, rejects duplicate IDs, and installs to `~/.config/omarchy/plugins/<id>/`.
- Plugins are activated via `omarchy-shell ipc enable-plugin <id>`.

## Frequently Asked Questions

### What happens if two Omarchy plugins share the same ID?

The shell rejects the installation immediately during the validation phase. The `id` field must be globally unique across all installed plugins, using reverse-domain namespacing like `com.company.pluginname` to prevent collisions.

### Can a single plugin manifest declare multiple kinds?

Yes. The `kinds` array accepts multiple entries such as `["bar", "panel"]`, and the corresponding `entryPoints` object must provide a QML file mapping for each declared kind. This allows one plugin to provide both a bar widget and a configuration panel.

### Where does Omarchy store installed plugin files?

After successful validation, the shell copies the plugin directory to `~/.config/omarchy/plugins/<id>/`, where `<id>` matches the plugin's declared identifier. The shell loads QML entry points from this location.

### What is the current schemaVersion for Omarchy manifests?

The Omarchy shell currently recognizes `schemaVersion: 1`. All new plugins should declare this integer value, as future shell versions may introduce schema changes requiring version detection for backward compatibility.