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

> Discover the Omarchy shell IPC targets. Learn about the eleven explicit panel targets, core shell target, and six implicit service targets for seamless inter-process communication.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: deep-dive
- Published: 2026-08-24

---

**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`](https://github.com/basecamp/omarchy/blob/main/runtime-smoke-test.sh) and [`shell-ipc-display-test.sh`](https://github.com/basecamp/omarchy/blob/main/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:

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

```

### Practical IPC Command Examples

Verify shell core availability:

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

```

Query current weather conditions:

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

```

Toggle Do-Not-Disturb mode:

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

```

Check media playback status (returns JSON):

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

```

Open the clock panel interface:

```bash
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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/runtime-smoke-test.sh) and [`shell-ipc-display-test.sh`](https://github.com/basecamp/omarchy/blob/main/shell-ipc-display-test.sh) exercise both explicit panel targets and implicit service targets to ensure correct request handling and response formatting.