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

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 (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 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 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:

# 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, adding or updating plugins never executes arbitrary code. The installer only clones the repository and validates the 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 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.

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