Omarchy Shell IPC Targets: Complete Guide to Inter-Process Communication Interfaces

The Omarchy shell exposes eleven explicit panel targets (prefixed with omarchy.), one core shell target for internal commands, and six implicit service targets (notifications, media, idle, lock, image-selector, osd) accessible via the Quickshell qs ipc utility.

The Omarchy desktop environment from basecamp/omarchy uses a specialized Inter-Process Communication (IPC) system to coordinate between its Qt Quick-based UI panels and background services. Each component that participates in this system declares an ipcTarget property in its QML definition that external scripts use to route commands through the shell's unified IPC socket at $OMARCHY_PATH/shell. These targets enable programmatic control of the desktop's weather displays, audio controls, notification management, and system monitoring features.

Explicit Panel IPC Targets in Omarchy

Panel components in Omarchy explicitly declare their IPC accessibility through the ipcTarget property defined in shell/Ui/Panel.qml. Each specialized panel in shell/plugins/panels/*/Panel.qml registers a unique string identifier under the omarchy. namespace, allowing external processes to query state and trigger actions.

Weather, Clock, and System Monitoring Targets

The following targets handle environmental and temporal information:

• omarchy.weather – Declared in shell/plugins/panels/weather/Panel.qml, provides current conditions and forecast data
• omarchy.clock – Defined in shell/plugins/panels/clock/Panel.qml, exposes time, calendar events, and alarm controls
• omarchy.monitor – Located in shell/plugins/panels/monitor/Panel.qml, manages external display information and configuration
• omarchy.agents – Found in shell/plugins/agents/Panel.qml, shows background agents and allows enable/disable toggles

Network and Connectivity Targets

Network-related panels expose VPN and connection state through dedicated targets:

• omarchy.tailscale – Defined in shell/plugins/panels/tailscale/Panel.qml, reports VPN connection state
• omarchy.network – Located in shell/plugins/panels/network/Panel.qml, displays active interfaces and upload/download rates
• omarchy.bluetooth – Declared in shell/plugins/panels/bluetooth/Panel.qml, handles device lists, pairing, and connection control

Power, Audio, and Cloud Integration

System resource panels use the following identifiers:

• omarchy.power – In shell/plugins/panels/power/Panel.qml, exposes battery level, charger status, and power actions
• omarchy.audio – Defined in shell/plugins/panels/audio/Panel.qml, provides volume sliders and output device selection
• omarchy.dropbox – Located in shell/plugins/panels/dropbox/Panel.qml, reports sync status and folder shortcuts

Implicit Service IPC Targets

Beyond the explicitly declared panel targets, Omarchy registers several implicit IPC targets through background service plugins. These do not appear as ipcTarget properties in QML files but are reachable through the same IPC mechanism via service registrations:

• notifications – Handles desktop notifications and Do-Not-Disturb (DND) toggle functionality
• media – Exposes playback status and media control commands
• idle – Reports system idle state and manages stay-awake requests
• lock – Controls screen lock status and security state
• image-selector – Opens UI dialogs for image selection operations
• osd – Manages On-Screen Display messages for system feedback

These targets are exercised in the repository's test suite under test/shell.d/, particularly in files like runtime-smoke-test.sh and shell-ipc-display-test.sh.

Core Shell IPC Target

The shell target serves as the primary communication endpoint for internal Omarchy commands. Implemented in the bin/omarchy-shell wrapper script, this target responds to system-level directives:

• ping – Verify shell responsiveness
• listPlugins – Enumerate available plugins
• setPluginEnabled – Toggle plugin activation states

This core target differs from panel targets because it manages the shell runtime itself rather than UI component state.

How to Invoke IPC Targets with qs ipc

Omarchy utilizes the Quickshell qs ipc command to route messages to specific targets. The command requires the -p flag pointing to the Omarchy socket path and follows this syntax:

qs ipc -n -p "$OMARCHY_PATH/shell" call <target> <command> [args...]

Practical IPC Command Examples

Verify shell core availability:

qs ipc -n -p "$OMARCHY_PATH/shell" call shell ping

Query current weather conditions:

qs ipc -n -p "$OMARCHY_PATH/shell" call omarchy.weather status

Toggle Do-Not-Disturb mode:

qs ipc -n -p "$OMARCHY_PATH/shell" call notifications setDnd true

Check media playback status (returns JSON):

qs ipc -n -p "$OMARCHY_PATH/shell" call media status

Open the clock panel interface:

qs ipc -n -p "$OMARCHY_PATH/shell" call omarchy.clock open

Summary

• Explicit targets use the ipcTarget property in shell/plugins/panels/*/Panel.qml files, creating namespaced identifiers like omarchy.weather and omarchy.audio
• Implicit targets (notifications, media, idle, lock, image-selector, osd) are registered by background services without QML declarations
• The shell target in bin/omarchy-shell handles core system commands including plugin management
• All targets communicate through the Quickshell IPC socket at $OMARCHY_PATH/shell using the qs ipc command-line tool
• IPC contracts are validated in test/shell.d/runtime-smoke-test.sh and related test files

Frequently Asked Questions

How do I discover all available IPC targets in Omarchy?

While Omarchy does not provide a single enumeration command for implicit targets, you can query the core shell target using qs ipc -n -p "$OMARCHY_PATH/shell" call shell listPlugins to see active plugins. For explicit panel targets, inspect the ipcTarget property values in shell/plugins/panels/*/Panel.qml files.

What distinguishes explicit from implicit IPC targets?

Explicit targets declare an ipcTarget string property directly in their QML Panel definition, making their IPC interface visible in the source code. Implicit targets are registered programmatically by service plugins (like notifications or media services) without a corresponding QML property, yet remain accessible through the same qs ipc command structure.

Can I call Omarchy IPC targets from shell scripts?

Yes. Any script with access to the $OMARCHY_PATH environment variable can invoke targets using the qs ipc -n -p "$OMARCHY_PATH/shell" call <target> <command> syntax. This enables automation of desktop functions like toggling DND, checking battery status via omarchy.power, or controlling media playback.

Where does Omarchy validate IPC target behavior?

The repository includes acceptance-style tests in test/shell.d/ that verify each target's IPC contract. Files such as runtime-smoke-test.sh and shell-ipc-display-test.sh exercise both explicit panel targets and implicit service targets to ensure correct request handling and response formatting.

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