How Third-Party Plugins Are Installed and Managed in Omarchy

Omarchy installs third-party plugins by cloning Git repositories containing a 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 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 is registered in the shell's internal plugin registry. This discovery process is documented in 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.

# 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 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.

# 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.

# 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.

# 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 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, stored in ~/.config/omarchy/plugins/
• Installation occurs via omarchy-plugin-add, which validates manifests and warns about unsandboxed execution
• The 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.

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.

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