How to Rescan and Reload Plugins in the Omarchy Shell

Execute omarchy-shell shell rescanPlugins to trigger a hot-reload of the Omarchy shell's plugin registry without restarting your session.

The Omarchy shell from basecamp/omarchy supports dynamic plugin management through a built-in rescan mechanism. When you modify, add, or remove plugins in the configuration directory, you can rescan and reload plugins to update the internal registry and activate changes immediately.

Understanding the Rescan Mechanism

The shell discovers plugins by traversing ~/.config/omarchy/plugins/ and system-wide directories at startup. The rescanPlugins() function defined in shell/shell.qml (around line 890) performs this walk dynamically, updating the internal registry and re-instantiating any changed QML components. This function is exposed through the Omarchy IPC layer, allowing both CLI and programmatic access to hot-reload functionality.

CLI Method: omarchy-shell Command

The simplest way to trigger a reload is using the dedicated CLI wrapper. When you run omarchy-shell shell rescanPlugins, the command forwards the request to the shell's IPC layer, which invokes the underlying rescan function. According to the source code, tools like bin/omarchy-plugin-add and bin/omarchy-plugin-remove execute this command after modifying plugin files to ensure the shell state remains synchronized.

IPC Method: shell_ipc for Automation

For shell scripts and automation, use the low-level IPC call directly. The command shell_ipc shell rescanPlugins performs the same operation without the CLI wrapper overhead. This method appears in the integration test suite at test/shell.d/runtime-smoke-test.sh (line 197), where it validates that plugins can be hot-reloaded without a full restart.

Automatic Rescans in Management Commands

Several built-in utilities automatically trigger rescans after plugin mutations:

• bin/omarchy-plugin-add: Calls the rescan command after installing a new plugin.
• bin/omarchy-plugin-remove: Triggers a reload after removal.
• bin/omarchy-plugin-enable and bin/omarchy-plugin-disable: These guards check for unknown plugins and suggest a rescan if the plugin registry appears out of sync, as implemented in their source.

Practical Workflow and Examples

Follow this pattern to deploy changes:

1. Install or modify plugin files in ~/.config/omarchy/plugins/<plugin-id>/.
2. Trigger the rescan using one of the methods below.
3. Verify the plugin appears in the registry.

# Example: Adding a custom clock widget manually

mkdir -p ~/.config/omarchy/plugins/omarchy.clock
cp -r /path/to/clock/source/* ~/.config/omarchy/plugins/omarchy.clock/

# Method 1: Interactive CLI rescan

omarchy-shell shell rescanPlugins

# Method 2: Direct IPC call in scripts

shell_ipc shell rescanPlugins >/dev/null
if [[ $? -eq 0 ]]; then
  echo "Plugin registry updated"
fi

# Method 3: Verification via IPC

shell_ipc shell listPlugins | jq '.'

The test suite demonstrates quiet rescanning for automation:

# From test/shell.d/runtime-smoke-test.sh (line 197)

shell_ipc_quiet shell rescanPlugins >/dev/null
plugins=$(shell_ipc shell listPlugins 2>/dev/null || true)
[[ -n "$plugins" ]] && echo "Hot-reload verified"

Key Source Files

Understanding these files provides deeper context for the rescan behavior:

• shell/shell.qml (line 890): Contains the rescanPlugins() function that implements the directory walk and component re-instantiation logic.
• docs/omarchy-shell.md: Documents the CLI usage including the rescanPlugins subcommand.
• agents/skills/shell-dev.md: Developer reference listing rescanPlugins among available IPC calls.
• bin/omarchy-plugin-enable and bin/omarchy-plugin-disable: Contain error handling that suggests rescans when plugins are not found.
• test/shell.d/runtime-smoke-test.sh: Integration testing that validates the hot-reload mechanism.

Summary

• The rescanPlugins() function in shell/shell.qml drives the plugin reload logic.
• Use omarchy-shell shell rescanPlugins for interactive rescans.
• Use shell_ipc shell rescanPlugins for programmatic control in scripts.
• Plugin management commands like omarchy-plugin-add automatically invoke rescans after file system changes.
• The shell walks ~/.config/omarchy/plugins/ and updates QML components without requiring a session restart.

Frequently Asked Questions

Where is the rescanPlugins() function defined in the Omarchy source code?

The function is defined in shell/shell.qml at approximately line 890. This QML function performs the directory traversal and updates the internal plugin registry.

Do I need to restart the Omarchy shell after installing a new plugin?

No. The shell supports hot-reloading. After placing files in ~/.config/omarchy/plugins/, run omarchy-shell shell rescanPlugins to activate the plugin immediately without restarting your session.

What is the difference between omarchy-shell and shell_ipc?

omarchy-shell is a high-level CLI wrapper that provides user-friendly output and error handling. shell_ipc is a low-level interface for programmatic communication; scripts use it directly to trigger rescanPlugins without CLI overhead, as seen in the test suite's automation scripts.

Why does my plugin still appear as unknown after I added it?

The shell caches the plugin registry. If a newly added plugin is not recognized, the registry is out of sync. Run omarchy-shell shell rescanPlugins to refresh the cache. The bin/omarchy-plugin-enable and bin/omarchy-plugin-disable scripts explicitly check for this condition and suggest a rescan when they detect unknown plugins.

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