How to Call a Method on a Loaded Omarchy Shell Plugin: The Complete IPC Guide

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 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) 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 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 <plugin-id> <method-name> <json-payload>

• <plugin-id>: The identifier string from the plugin's manifest.json (e.g., omarchy.emojis).
• <method-name>: The exported function name defined in the plugin's service module.
• <json-payload>: 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 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:

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:

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:

#!/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 (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/<plugin-name>/Service.js:

// 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) 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: Scans plugin directories, validates manifest.json files, and maintains the mapping between plugin IDs and their service objects.
• 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: Reference implementation showing how to structure service modules with exported IPC functions.

Summary

• Plugin Discovery: The registry at shell/registry.js loads plugins from ~/.config/omarchy/plugins/ based on manifest.json declarations.
• IPC Syntax: Use omarchy-shell ipc <plugin-id> <method-name> <json-payload> 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 module logs validation results during startup. If the 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 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.

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