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

> Explore Omarchy shell IPC methods including socket-based communication and lifecycle verbs. Discover how plugins register targets for specialized commands in this comprehensive guide.

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

---

**The Omarchy shell exposes a socket-based IPC contract centered on a core `shell` target with lifecycle verbs like `open`, `close`, and `setConfig`, while each plugin registers its own named target for specialized commands.**

The Omarchy shell in the `basecamp/omarchy` repository communicates with external processes through a well-defined **IPC (inter-process communication)** protocol. All interactions route through the `omarchy-shell` CLI wrapper, which forwards commands to the running QML/C++ core over a socket-based interface. Understanding these IPC methods allows developers and users to programmatically control shell visibility, configuration, and plugin behavior.

## Core IPC Architecture

The IPC system relies on a **single primary target** called `shell` that exposes stable lifecycle and configuration verbs. According to [`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md), the contract guarantees **type-stable** string-only arguments, accepting values like `"1"`, `"yes"`, or omitted values for boolean flags. All commands flow through the thin wrapper script located at `bin/omarchy-shell`, which parses arguments and transmits them to the active shell process.

## Core Shell IPC Verbs

The `shell` target supports eight primary verbs for controlling the application state and configuration:

- **`open`**: Displays the shell or a specific panel.  
  Example: `omarchy-shell shell open`

- **`close`**: Hides the shell immediately.  
  Example: `omarchy-shell shell close`

- **`toggle`**: Switches visibility between shown and hidden states.  
  Example: `omarchy-shell shell toggle`

- **`refresh`**: Reloads configuration files without restarting the UI.  
  Example: `omarchy-shell shell refresh`

- **`rescanPlugins`**: Scans `~/.config/omarchy/plugins` for new or removed plugins.  
  Example: `omarchy-shell shell rescanPlugins`

- **`reload`**: Forces a complete UI reload, useful after theme modifications.  
  Example: `omarchy-shell shell reload`

- **`setConfig <key> <value>`**: Updates runtime configuration values. Accepts nested keys like `theme accent`.  
  Example: `omarchy-shell shell setConfig theme accent "#ff6600"`

- **`getConfig <key>`**: Retrieves current configuration values.  
  Example: `omarchy-shell shell getConfig theme accent`

## Plugin-Specific IPC Targets

Beyond the core shell, **each installed plugin registers its own IPC target** named after its identifier (e.g., `omarchy.agents`, `omarchy.backup`, `omarchy.menu`). As documented in [`shell/plugins/README.md`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/README.md), these targets inherit common verbs (`open`, `close`, `toggle`, `refresh`) and expose custom functionality:

- **`omarchy.agents`**: Defines `next`, `prev`, `refresh`, and `toggle` verbs for navigating agent panels (source: [`shell/plugins/agents/README.md`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/agents/README.md)).

- **`omarchy.backup`**: Provides `run`, `status`, and `refresh` verbs for triggering and monitoring backup operations (source: [`plans/backup.md`](https://github.com/basecamp/omarchy/blob/main/plans/backup.md)).

## Practical IPC Usage Examples

The following commands demonstrate real-world IPC interactions through the `bin/omarchy-shell` wrapper:

```bash

# Core shell visibility control

omarchy-shell shell open
omarchy-shell shell toggle

# Runtime configuration changes

omarchy-shell shell setConfig theme accent "#0f62fe"
omarchy-shell shell getConfig theme accent

# Plugin-specific operations

omarchy-shell omarchy.agents next
omarchy-shell omarchy.backup run
omarchy-shell omarchy.backup status

```

## Implementation and Protocol Details

The IPC protocol implementation in `basecamp/omarchy` ensures backward compatibility through **string-only argument passing**. The wrapper script at `bin/omarchy-shell` handles socket communication transparently, making the interface agnostic to the underlying QML/C++ core. For developers extending the shell, [`agents/skills/shell-dev.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/shell-dev.md) provides guidelines for registering new IPC targets within custom plugins, ensuring that new verbs follow the same type-stable conventions as the core `shell` target.

## Summary

- The Omarchy shell uses a **socket-based IPC protocol** with a central `shell` target and plugin-specific targets.
- Core verbs include **`open`**, **`close`**, **`toggle`**, **`refresh`**, **`reload`**, **`rescanPlugins`**, **`setConfig`**, and **`getConfig`**.
- Plugins register **dedicated targets** (e.g., `omarchy.agents`) with both standard and custom verbs.
- All commands route through the **`bin/omarchy-shell`** wrapper, ensuring type-stable string argument handling.
- Configuration updates apply immediately at runtime without requiring process restarts.

## Frequently Asked Questions

### How do I invoke IPC commands against the Omarchy shell?

All IPC interactions flow through the `omarchy-shell` command-line wrapper located at `bin/omarchy-shell`. This script parses your arguments and forwards them to the running shell process over the internal socket protocol. You never interact with the socket directly; the wrapper handles target selection and message serialization according to the contract defined in [`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md).

### What argument types does the setConfig verb accept?

The IPC contract guarantees **type-stable string-only arguments**. You may pass `"1"`, `"yes"`, `"true"`, or omit the value entirely to enable boolean flags. For configuration keys, use space-separated paths like `theme accent` to target nested configuration values, followed by the string value to assign.

### Can third-party plugins expose their own IPC methods?

Yes. Every plugin registers its own **IPC target** named after its plugin identifier. According to the plugin system documented in [`shell/plugins/README.md`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/README.md), plugins automatically gain standard lifecycle verbs (`open`, `close`, `toggle`, `refresh`) and can define custom verbs specific to their functionality, such as the `run` and `status` commands found in the backup plugin.

### Where is the IPC contract documented in the source code?

The definitive IPC contract specification resides in [`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md), which details the string-argument protocol and target naming conventions. Implementation details for the wrapper script appear in `bin/omarchy-shell`, while plugin-specific extensions are documented in individual [`README.md`](https://github.com/basecamp/omarchy/blob/main/README.md) files within `shell/plugins/` subdirectories.