# IPC Methods Available for the Omarchy Shell: Complete API Reference

> Explore Omarchy shell IPC methods for remote theme application, plugin management, and more. Access 13 public IPC methods via IpcHandler for external script and DBus client integration.

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

---

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

```bash

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

```bash

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

```bash

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

```bash

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

```javascript
// 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.