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

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, 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, 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).

• omarchy.backup: Provides run, status, and refresh verbs for triggering and monitoring backup operations (source: plans/backup.md).

Practical IPC Usage Examples

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

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

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, 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, 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 files within shell/plugins/ subdirectories.

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