# How to Rescan and Reload Plugins in the Omarchy Shell

> Quickly rescan and reload plugins in the Omarchy shell with a simple command. Keep your Omarchy session updated without interruption. Learn how to trigger a hot-reload now.

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

---

**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`](https://github.com/basecamp/omarchy/blob/main/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.

```bash

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

```

```bash

# Method 1: Interactive CLI rescan

omarchy-shell shell rescanPlugins

```

```bash

# Method 2: Direct IPC call in scripts

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

```

```bash

# Method 3: Verification via IPC

shell_ipc shell listPlugins | jq '.'

```

The test suite demonstrates quiet rescanning for automation:

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md)**: Documents the CLI usage including the `rescanPlugins` subcommand.
- **[`agents/skills/shell-dev.md`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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.