# How Third-Party Plugins Are Installed and Managed in Omarchy

> Discover how Omarchy installs and manages third-party plugins by cloning Git repos and updating a JSON registry. Learn the CLI commands for seamless integration.

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

---

**Omarchy installs third-party plugins by cloning Git repositories containing a [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) into `~/.config/omarchy/plugins/` and manages them through CLI commands that update a JSON registry and signal the running shell via IPC.**

Omarchy, the extensible shell environment from Basecamp, treats every plugin as a standard Git repository with a declarative manifest. Understanding how third-party plugins are installed and managed in Omarchy requires examining its file-system-based workflow that eschews package managers in favor of direct Git operations and JSON configuration.

## Plugin Discovery and Manifest Structure

Every valid plugin must contain a **[`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json)** at its root describing the plugin's identity, kind(s), and entry points. At startup, the shell recursively scans two distinct locations to build its plugin registry:

- **First-party plugins**: Bundled plugins living in `$OMARCHY_PATH/shell/plugins/`
- **Third-party plugins**: User-added repositories stored under `~/.config/omarchy/plugins/`

Any folder containing a valid [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) is registered in the shell's internal plugin registry. This discovery process is documented in [`manual/32-shell-plugins.md`](https://github.com/basecamp/omarchy/blob/main/manual/32-shell-plugins.md) and operates purely through filesystem introspection without network calls.

## Installing Third-Party Plugins with `omarchy-plugin-add`

The command **`omarchy-plugin-add <git-url>`** serves as the primary entry point for adding third-party plugins. According to the implementation in `bin/omarchy-plugin-add`, the command executes the following sequence:

1. Displays a security warning that the plugin will execute **unsandboxed code** and requires user confirmation
2. Clones the repository into a temporary staging directory
3. Validates the manifest using **`omarchy-plugin-validate`** to ensure compliance with the plugin registry contract
4. Verifies the plugin ID is not already registered
5. Moves the validated copy to `~/.config/omarchy/plugins/<id>/`
6. Optionally enables the plugin immediately if `--enable` is passed

No install hooks are executed and no `sudo` privileges are required—the entire process remains confined to file-system operations.

```bash

# Add a plugin with interactive confirmation

omarchy-plugin-add https://github.com/omarchy/omarchy-clock.git

# Add and enable in one step

omarchy-plugin-add https://github.com/omarchy/omarchy-clock.git --enable

```

## Enabling, Disabling, and Runtime Management

Plugin activation is controlled through **`~/.config/omarchy/shell.json`**. Enabling a plugin writes its ID to the appropriate section—either as an entry in the `plugins` array, as a bar layout entry, or as `bar.id` depending on the plugin kind.

The management commands function as follows:

- **`omarchy-plugin-enable <id>`**: Updates [`shell.json`](https://github.com/basecamp/omarchy/blob/main/shell.json) and signals the running shell via IPC to load the plugin
- **`omarchy-plugin-disable <id>`**: Removes the ID from the active configuration and triggers an IPC reload

First-party plugins that are not bar widgets start enabled by default; their disabled state is tracked separately in `disabledPlugins[]` within the same JSON file. This architecture allows the shell to maintain state without modifying the plugin files themselves.

```bash

# Enable an already installed plugin

omarchy-plugin-enable omarchy.clock

# Disable a plugin

omarchy-plugin-disable omarchy.clock

```

## Local Development and Cloning

For developers modifying existing plugins, the **`omarchy-plugin-clone`** command creates an editable copy of any enabled plugin. As implemented in `bin/omarchy-plugin-clone`:

- Copies the plugin from `~/.config/omarchy/plugins/<id>/` to a new directory under the same path
- Preserves all sub-components including dependencies
- Opens the cloned copy immediately in `$EDITOR` when using the `--edit` flag
- Automatically re-enables the copy, replacing the original instance in the running shell while retaining layout and settings

This workflow allows safe experimentation without affecting the original plugin installation.

```bash

# Clone for local editing (opens editor automatically)

omarchy-plugin-clone omarchy.clock --edit

```

## Removing and Listing Plugins

The **`omarchy-plugin-remove`** command handles uninstallation with safety measures:

1. First disables the plugin to prevent runtime errors
2. If the directory is a Git checkout, deletes the folder while preserving the upstream remote reference
3. If the folder is a plain directory (not a Git repo), moves it to a timestamped backup inside `~/.config/omarchy/plugins/` rather than permanent deletion

For inventory management, **`omarchy-plugin-list`** queries the shell via IPC and outputs a JSON array of all discovered plugins, including flags indicating which are currently enabled.

```bash

# Remove a plugin (disables first, then deletes or backs up)

omarchy-plugin-remove omarchy.clock

# List all plugins with enabled status

omarchy-plugin-list

```

## Validation and Hot-Reload Architecture

Before any plugin can be added or enabled, **`bin/omarchy-plugin-validate`** checks the manifest against the shell's plugin registry contract. This validation ensures proper kinds, required entry points, and safe ID naming conventions. The test suite in [`test/shell.d/plugin-validate-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/plugin-validate-test.sh) enforces these requirements programmatically.

During development, Omarchy monitors `~/.config/omarchy/plugins/` for file changes and automatically hot-reloads affected plugins. This allows developers to edit code and see changes immediately without restarting the shell.

## Summary

- Plugins are standard Git repositories containing a [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json), stored in `~/.config/omarchy/plugins/`
- Installation occurs via **`omarchy-plugin-add`**, which validates manifests and warns about unsandboxed execution
- The **[`shell.json`](https://github.com/basecamp/omarchy/blob/main/shell.json)** file tracks enabled state, modified by **`omarchy-plugin-enable`** and **`omarchy-plugin-disable`**
- Local development uses **`omarchy-plugin-clone`** to create editable copies with automatic hot-reload
- Validation logic resides in **`bin/omarchy-plugin-validate`** and its corresponding test suite

## Frequently Asked Questions

### Where are third-party plugins stored in Omarchy?

Third-party plugins are stored in `~/.config/omarchy/plugins/<plugin-id>/` after being cloned and validated from their Git source. This location is separate from first-party plugins bundled in `$OMARCHY_PATH/shell/plugins/`.

### Does Omarchy require elevated permissions to install plugins?

No. The installation process in `bin/omarchy-plugin-add` operates entirely within the user's home directory and requires no `sudo` privileges or install hooks. The only network activity is the initial `git clone` operation.

### What happens if I modify a plugin while the shell is running?

Omarchy's hot-reload system detects file changes inside `~/.config/omarchy/plugins/` and automatically reloads the affected plugin. This allows real-time development without shell restarts, as verified by the test suite in [`test/shell.d/plugin-clone-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/plugin-clone-test.sh).

### How does Omarchy validate plugin manifests before installation?

The `bin/omarchy-plugin-validate` utility checks each manifest against the plugin registry contract, verifying kinds, entry points, and ID naming conventions. This validation runs during the staging phase of `omarchy-plugin-add` before files are moved to the final installation directory.