IPC Methods Available for the Omarchy Shell: Complete API Reference

The Omarchy shell exposes 13 public IPC methods through its IpcHandler component targeting "shell", enabling remote theme application, dynamic plugin management, bar widget manipulation, and configuration reloading from external scripts or DBus clients.

The basecamp/omarchy repository implements a robust inter-process communication system that allows external tools to control the desktop shell without restarting it. These IPC methods available for the Omarchy shell are defined within the IpcHandler block in shell/shell.qml (lines 71-100) and are accessible via the omarchy-summon CLI wrapper or direct DBus calls.

Core IPC Architecture

Omarchy’s shell leverages Quickshell’s IPC framework to expose functions remotely. The IpcHandler component in shell/shell.qml acts as the central dispatcher, routing incoming messages to specific QML functions based on the method name. Each method accepts string parameters (often Base64-encoded JSON) and returns string responses, making them compatible with standard Unix piping and DBus interfaces.

The handler is configured with target: "shell", meaning clients must address their IPC messages to the omarchy.shell namespace. Individual plugins may register their own handlers (e.g., omarchy.image-picker), but the core shell IPC remains centralized in the main QML file.

Complete List of Shell IPC Methods

The following methods are implemented in shell/shell.qml and are available to any authorized client:

System Health and Configuration

• ping() – Returns "ok" for health checks. Implemented at lines 75-77.
• reloadConfig() – Hot-reloads the user’s shell.json via userConfigFile.reload(). Returns "ok" on success.
• listShellConfig() – Returns the effective merged configuration as a JSON string, useful for debugging user settings.
• debugBarGeometry() – Outputs a JSON description of the bar’s current geometry and positioning for troubleshooting layout issues.

Theme and Appearance Management

• applyTheme(colorsB64: string, shellB64: string) – Decodes Base64-encoded theme data and shell configuration JSON, then invokes Color.loadColors() and Color.loadShell() before scheduling a UI refresh. Defined at lines 79-88.
• toggleBarTransparency() – Toggles compositor transparency for the bar if one exists. Returns "ok" when successful or "no-bar" if no bar component is active.

Plugin Lifecycle Management

• rescanPlugins() – Forces the shell to reload all installed plugins by calling shell.reloadPlugins(). Defined at lines 90-92. Returns void.
• listPlugins() – Returns a JSON array describing every installed plugin, including id, name, kinds, and current state. Implemented at lines 52-88.
• setPluginEnabled(id: string, enabled: string) – Enables or disables a plugin by ID, where enabled must be the string "true" or "false".
• enablePlugin(id: string, placementJson: string) – Activates a plugin and optionally assigns it a placement configuration (used primarily for bar widgets).

Bar Widget Manipulation

• putBarWidget(id: string, placementJson: string) – Adds a bar widget if not already present, using the provided placement JSON to determine position and sizing.
• moveBarWidget(id: string, placementJson: string) – Relocates an existing bar widget to a new placement defined in the JSON parameter.
• setBarWidget(id: string, key: string, valueJson: string, selectorJson: string) – Modifies a specific property on a bar widget. The valueJson parameter contains the JSON-encoded value, while selectorJson optionally scopes the change to specific widget instances.

Invoking IPC Methods via Command Line

For shell scripting and terminal usage, Omarchy provides the omarchy-summon helper that forwards arguments to the IPC layer. The syntax follows omarchy-summon shell <method> [args...].

Health check and configuration commands:

# Verify shell responsiveness

omarchy-summon shell ping

# → ok

# Reload configuration without restarting the session

omarchy-summon shell reloadConfig

# → ok

# Export current configuration for backup or inspection

omarchy-summon shell listShellConfig > current-shell.json

Theme application requires Base64 encoding:

# Apply new theme colors and shell configuration

COLORS_B64=$(base64 -w0 < theme-colors.json)
SHELL_B64=$(base64 -w0 < shell-config.json)
omarchy-summon shell applyTheme "$COLORS_B64" "$SHELL_B64"

# → ok

Plugin enumeration and management:

# List all installed plugins with jq formatting

omarchy-summon shell listPlugins | jq .

# Disable a specific plugin

omarchy-summon shell setPluginEnabled "weather-widget" "false"

# Rescan plugin directory after installing new extensions

omarchy-summon shell rescanPlugins

Bar widget operations:

# Add a widget to the bar with placement configuration

omarchy-summon shell putBarWidget "clock" '{"anchor": "right", "margin": 10}'

# Move existing widget to center

omarchy-summon shell moveBarWidget "clock" '{"anchor": "center"}'

# Toggle transparency for aesthetic changes

omarchy-summon shell toggleBarTransparency

Programmatic IPC Access via DBus

Scripts and applications written in JavaScript or Qt can communicate directly with the shell over DBus without spawning subprocesses. The shell.summon() method accepts the target namespace and a JSON-serialized request object.

Example JavaScript invocation:

// Query available plugins programmatically
let result = shell.summon("omarchy.shell", JSON.stringify({
  method: "listPlugins"
}));
let plugins = JSON.parse(result);
console.log(`Found ${plugins.length} installed plugins`);

// Enable a plugin with specific placement
shell.summon("omarchy.shell", JSON.stringify({
  method: "enablePlugin",
  args: ["system-monitor", '{"panel": "top", "index": 3}']
}));

This approach reduces overhead for frequent operations and enables tight integration with system trays or settings panels.

Source Code Location and Implementation Details

The IPC system is implemented across several key files in the basecamp/omarchy repository:

• shell/shell.qml – Contains the primary IpcHandler block (lines 71-100) implementing all 13 core methods. Individual method implementations are located at:

  • ping(): lines 75-77
  • applyTheme(): lines 79-88
  • rescanPlugins(): lines 90-92
  • listPlugins(): lines 52-88

• shell/Ui/Panel.qml – Provides a generic IpcHandler pattern used by panel plugins, demonstrating how ipcTarget is wired for individual plugin namespaces (e.g., omarchy.<plugin>).

• shell/plugins/*/*.qml – Individual plugin directories containing specialized IPC handlers that extend the core shell functionality with domain-specific remote procedures.

All methods return strings to ensure compatibility with DBus string type constraints, with complex data structures serialized as JSON strings within those returns.

Summary

• The Omarchy shell exposes 13 public IPC methods centralized in shell/shell.qml via the IpcHandler component targeting "shell".
• Configuration and theme changes can be applied dynamically without process restarts using reloadConfig() and applyTheme().
• Plugin management supports enumeration, enabling/disabling, and rescanning through methods like listPlugins() and setPluginEnabled().
• Bar widget manipulation provides granular control over placement and properties via putBarWidget(), moveBarWidget(), and setBarWidget().
• Integration options include the omarchy-summon CLI for shell scripts and direct DBus calls for applications requiring low-latency communication.

Frequently Asked Questions

How do I check if the Omarchy shell is running and responsive?

Use the ping() IPC method, which is implemented at lines 75-77 in shell/shell.qml. From the terminal, run omarchy-summon shell ping; if the shell process is active, it returns the string "ok" immediately without modifying any state.

Can I change themes without restarting the Omarchy shell?

Yes. The applyTheme(colorsB64, shellB64) method accepts Base64-encoded JSON configurations for both color schemes and shell layouts, then hot-applies them via Color.loadColors() and Color.loadShell(). This allows instant theme switching without session interruption.

What is the difference between enablePlugin() and setPluginEnabled()?

setPluginEnabled(id, enabled) toggles a plugin’s active state using a boolean string ("true" or "false"), while enablePlugin(id, placementJson) specifically activates a plugin and simultaneously assigns it a placement configuration required for bar widgets. Use the latter when adding UI elements to the bar, and the former for general state management.

Where are the IPC method implementations located in the source code?

All core shell IPC methods are defined within the IpcHandler block in shell/shell.qml between lines 71 and 100. Specific functions like ping() occupy lines 75-77, applyTheme() spans lines 79-88, and rescanPlugins() is found at lines 90-92. Plugin-specific IPC handlers follow the same pattern in their respective shell/plugins/*/ directories.

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