# How Omarchy Plugins Are Updated: The Git-Based Hot-Reload System

> Discover how Omarchy plugins update using a Git hot-reload system. Fetch changes, review diffs, and seamlessly update your shell without a full restart.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: internals
- Published: 2026-09-04

---

**Omarchy updates plugins through a Git-based workflow that fetches remote changes, displays a diff for review, fast-forwards the local checkout upon confirmation, and hot-reloads the shell without restarting the desktop.**

Omarchy treats every UI element—from status bars to lock screens—as a plugin managed through standard Git operations. Understanding how Omarchy plugins are updated requires examining the CLI's fetch-diff-merge pattern and the `PluginRegistry.qml` hot-reload mechanism defined in the source repository.

## The Git-Based Update Mechanism

The `omarchy plugin update <id>` command, defined in `bin/omarchy` under the plugin command group, implements a transparent, non-destructive update flow. According to [`shell/README.md`](https://github.com/omacom/omarchy/blob/main/shell/README.md) (lines 105-108), the system treats each plugin directory as a standard Git repository and follows a strict fetch-review-merge sequence.

### Fetch, Diff, and Fast-Forward Workflow

When executing an update, the CLI performs these discrete operations:

1. **Locates the repository** at `~/.config/omarchy/plugins/<id>/` for third-party plugins or the built-in path at `$OMARCHY_PATH/shell/plugins/` for first-party components
2. **Fetches remote changes** using `git fetch` without modifying the working tree
3. **Generates a preview** via `git diff HEAD..origin/<branch>` to display exactly which files will change
4. **Fast-forwards the branch** using `git merge --ff-only origin/<branch>` only after user confirmation (or with `--yes` to skip prompts)

This design prevents silent overwrites and ensures users can audit code changes before application.

### Batch Updates

To update all Git-managed plugins simultaneously, run `omarchy plugin update` without specifying an ID. Append the `--yes` flag to bypass individual diff reviews and fast-forward all repositories automatically.

## Hot-Reload Without Restart

After a successful merge, Omarchy applies changes immediately without restarting the desktop session. The command `omarchy-shell shell rescanPlugins` triggers `PluginRegistry.qml` to re-scan both `$OMARCHY_PATH/shell/plugins/` and `~/.config/omarchy/plugins/`, validating each [`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json) and reloading modified QML components while preserving the current session state.

## Plugin Discovery and Storage

The update mechanism relies on Omarchy's strict directory hierarchy and manifest contract.

### First-Party vs. Third-Party Paths

- **Built-in plugins**: Reside in `$OMARCHY_PATH/shell/plugins/`, shipped with the core system
- **User plugins**: Installed in `~/.config/omarchy/plugins/<id>/`, managed as standalone Git repositories

Both locations follow identical structural requirements, but the CLI update command primarily targets user directories where third-party code lives.

### The Manifest Contract

Every plugin directory must contain a [`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json) describing the `id`, `kind`, entry point, and optional flags such as `keepLoaded`. During `rescanPlugins`, the registry validates this file, ensuring corrupted or incompatible plugins fail gracefully before the shell attempts to load them.

### Enabled State Configuration

Plugin activation is controlled by `~/.config/omarchy/shell.json`. Third-party plugins enable when referenced as bar widgets or panel entries, while first-party plugins default to enabled unless explicitly listed in the `disabledPlugins[]` array.

## CLI Commands for Plugin Management

The `omarchy` binary provides complete lifecycle management through the plugin command group:

```bash

# Install a third-party plugin from any Git URL (disabled by default)

omarchy plugin add https://github.com/acme/omarchy-weather.git

# Enable the plugin in your configuration

omarchy plugin enable omarchy.weather

# Update specific plugin with diff review

omarchy plugin update omarchy.weather

# Update all plugins non-interactively

omarchy plugin update --yes

# Clone a built-in plugin to your config for editing

omarchy plugin clone omarchy.clock

# Remove plugin completely

omarchy plugin remove omarchy.weather

```

## Safety and Manual Operations

As documented in [`shell/README.md`](https://github.com/omacom/omarchy/blob/main/shell/README.md), adding or updating plugins never executes arbitrary code. The installer only clones the repository and validates the [`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json). Because plugins are standard Git repositories, users can bypass the CLI and run manual Git operations inside `~/.config/omarchy/plugins/<id>/`, such as pinning to specific refs or switching branches, while maintaining compatibility with the update system.

## Summary

- Omarchy plugins are updated via the `omarchy plugin update <id>` command, which wraps standard Git operations
- The workflow fetches remote changes, displays a diff for review, and fast-forwards only with explicit confirmation or the `--yes` flag
- User plugins reside in `~/.config/omarchy/plugins/<id>/` as standard Git repositories, while built-in plugins follow the same mechanics in `$OMARCHY_PATH/shell/plugins/`
- Updates hot-reload immediately via `omarchy-shell shell rescanPlugins` without requiring a session restart
- Each plugin requires a valid [`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json) that the `PluginRegistry.qml` validates during the rescan process
- The security model ensures plugin installation and updates never run arbitrary code—only standard Git clone and fetch operations

## Frequently Asked Questions

### How does Omarchy handle plugin updates safely?

Omarchy treats plugin updates as Git fast-forwards that fetch remote changes and display a diff before merging. This prevents silent overwrites and allows users to review code changes before the `omarchy-shell` process reloads the plugin via `rescanPlugins`.

### Where are third-party Omarchy plugins stored on disk?

Third-party plugins live in `~/.config/omarchy/plugins/<id>/` as standard Git repositories. First-party plugins reside in `$OMARCHY_PATH/shell/plugins/`, but users can clone them to their personal config directory using `omarchy plugin clone <id>` for local modification.

### Can I update all Omarchy plugins at once?

Yes. Running `omarchy plugin update` without arguments updates every Git-managed plugin in `~/.config/omarchy/plugins/`. Use the `--yes` flag to skip individual diff reviews and apply all available updates automatically.

### What happens if an update breaks a plugin?

Because Omarchy uses standard Git repositories, you can manually revert to the previous commit in `~/.config/omarchy/plugins/<id>/` using commands like `git reset --hard HEAD~1`, then run `omarchy-shell shell rescanPlugins` to reload the stable version without restarting your desktop session.