# How to Call a Method on a Loaded Omarchy Shell Plugin: The Complete IPC Guide > Learn to call methods on loaded Omarchy shell plugins using the omarchy-shell ipc command. This guide explains the process and payload for effective Inter-Process Communication. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: how-to-guide - Published: 2026-08-30 --- **Call methods on loaded Omarchy shell plugins using the `omarchy-shell ipc` command followed by the plugin ID, method name, and JSON payload.** The **Omarchy** desktop environment manages shell plugins through a dynamic registry system that exposes service methods via inter-process communication (IPC). To call a method on a loaded Omarchy shell plugin, you interact with the IPC dispatcher defined in [`shell/ipc.js`](https://github.com/omacom/omarchy/blob/main/shell/ipc.js) and invoked through the CLI entry point at `bin/omarchy`. This architecture allows external scripts and command-line tools to trigger functionality exposed by active plugins. ## How Omarchy Loads and Registers Plugins The **Plugin Registry** ([`shell/registry.js`](https://github.com/omacom/omarchy/blob/main/shell/registry.js)) automatically discovers and loads plugins from `~/.config/omarchy/plugins/` or the system-wide `$OMARCHY_PATH/plugins/` directory during shell startup. Each plugin directory must contain a [`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json) file declaring the plugin's **id**, supported **kinds** (such as `service`, `panel`, or `bar-widget`), and entry-point file paths. The registry validates these manifests and registers every entry point under the plugin's unique identifier. For **service-type** plugins, the entry point is a JavaScript module that exports IPC-exposed functions. The registry maintains a map of these service objects, enabling the IPC dispatcher to route incoming calls to the correct plugin instance. ## IPC Command Structure for Plugin Method Calls The generic format for calling a method on a loaded Omarchy shell plugin follows this strict token-based syntax: ``` omarchy-shell ipc ``` - **``**: The identifier string from the plugin's [`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json) (e.g., `omarchy.emojis`). - **``**: The exported function name defined in the plugin's service module. - **``**: A JSON string containing method arguments, or `{}` for methods accepting no parameters. The `omarchy-shell` binary (`bin/omarchy`) parses this command and delegates to the [`shell/ipc.js`](https://github.com/omacom/omarchy/blob/main/shell/ipc.js) dispatcher, which looks up the plugin's service object and invokes the requested method with the deserialized payload. ## Calling Plugin Methods from the Command Line ### Basic IPC Invocation To call a method on a loaded Omarchy shell plugin from the terminal, use the `ipc` subcommand with the plugin ID and method name. The following example invokes the `summon` method on the emojis plugin: ```bash omarchy-shell ipc omarchy.emojis summon "{}" ``` This command returns the value sent back by the service function (e.g., `ok`). The JSON payload must be valid JSON, even when empty. For methods requiring arguments, pass a serialized JSON object: ```bash omarchy-shell ipc my-plugin setBrightness '{"level":75}' ``` ### Bash Script Integration via shell_ipc The Omarchy test suite defines a `shell_ipc` helper function that simplifies programmatic calls from shell scripts. Source the helpers file to access this function: ```bash #!/usr/bin/env bash source "$ROOT/test/shell.d/helpers.sh" # Call the hide method on the emojis plugin result=$(shell_ipc shell hide omarchy.emojis) if [[ $result == "ok" ]]; then echo "Emojis panel hidden successfully" fi ``` As shown in [`test/shell.d/runtime-smoke-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/runtime-smoke-test.sh) (lines 160-162), this pattern is used extensively in the Omarchy test suite to verify plugin functionality during runtime smoke tests. ## Implementing Callable Methods in Plugin Services To expose a method callable via IPC, export a function from your plugin's service JavaScript file. The function receives the JSON payload as its first argument and must return a JSON-serializable value. Create or edit the service file in `shell/plugins//Service.js`: ```javascript // shell/plugins/my-plugin/Service.js export function setBrightness(args) { const { level } = JSON.parse(args); // Implementation logic here return "ok"; } export function getStatus(args) { return JSON.stringify({ active: true, timestamp: Date.now() }); } ``` The **Plugin Registry** ([`shell/registry.js`](https://github.com/omacom/omarchy/blob/main/shell/registry.js)) automatically maps these exports to the plugin ID, making them accessible through the IPC dispatcher without additional registration steps. ## Core Implementation Files Understanding these source files is essential for debugging or extending plugin IPC functionality: - **[`shell/registry.js`](https://github.com/omacom/omarchy/blob/main/shell/registry.js)**: Scans plugin directories, validates [`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json) files, and maintains the mapping between plugin IDs and their service objects. - **[`shell/ipc.js`](https://github.com/omacom/omarchy/blob/main/shell/ipc.js)**: Contains the core IPC dispatcher logic that routes `omarchy-shell ipc` commands to the appropriate plugin service and handles method invocation. - **`bin/omarchy`**: The CLI entry point that parses the `ipc` subcommand and forwards arguments to the IPC layer. - **[`shell/plugins/emojis/Service.js`](https://github.com/omacom/omarchy/blob/main/shell/plugins/emojis/Service.js)**: Reference implementation showing how to structure service modules with exported IPC functions. ## Summary - **Plugin Discovery**: The registry at [`shell/registry.js`](https://github.com/omacom/omarchy/blob/main/shell/registry.js) loads plugins from `~/.config/omarchy/plugins/` based on [`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json) declarations. - **IPC Syntax**: Use `omarchy-shell ipc ` to call any exported service method. - **Service Implementation**: Export functions from your plugin's service JavaScript file; the first argument receives the parsed JSON payload. - **Script Integration**: Use the `shell_ipc` helper from the test suite for reliable programmatic access in Bash scripts. - **Response Handling**: Methods must return JSON-serializable values that propagate back to the CLI caller. ## Frequently Asked Questions ### How do I verify that a plugin is loaded before calling its methods? Check the shell logs or query the plugin registry state. The [`shell/registry.js`](https://github.com/omacom/omarchy/blob/main/shell/registry.js) module logs validation results during startup. If the [`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json) is valid and the plugin directory exists in `~/.config/omarchy/plugins/`, the plugin is automatically registered and ready to receive IPC calls. ### Can I pass complex data structures to plugin methods? Yes. The JSON payload parameter accepts any valid JSON-serializable object. In your service implementation, parse the `args` parameter using `JSON.parse(args)` to access nested objects, arrays, or primitive values. Ensure your return values are also JSON-serializable to maintain IPC compatibility. ### What happens if I call a method that does not exist in the plugin? The IPC dispatcher in [`shell/ipc.js`](https://github.com/omacom/omarchy/blob/main/shell/ipc.js) attempts to look up the method name on the plugin's service object. If the method is not exported or is undefined, the call will fail with an error indicating the missing method. Always verify that your service module exports the function using the exact name referenced in your IPC command. ### Is there a performance difference between CLI calls and direct internal calls? CLI calls using `omarchy-shell ipc` incur serialization overhead due to JSON parsing and the subprocess invocation through `bin/omarchy`. For high-frequency operations within the shell process itself, use direct JavaScript imports rather than the IPC interface. Reserve IPC for cross-process communication or external script integration.