☰

IPC Reference - MorgenWM

IPC Reference

MorgenWM exposes a Niri-compatible IPC over a Unix domain socket. Any bar or tool that speaks the Niri IPC protocol works out of the box.

Socket Path

The socket is at $XDG_RUNTIME_DIR/morgenwm.sock by default. Override with the $NIRI_SOCKET environment variable.

Protocol

Communication uses newline-delimited JSON over a Unix stream socket. Each request is a single JSON line; each response is a single JSON line.

Queries

Queries are sent as a JSON string (e.g. "Outputs"). Responses are wrapped in {"Ok": ...} on success or {"Err": "message"} on error.

`morgenwm_msg outputs`

Returns all connected outputs with their current mode, position, and physical dimensions.

morgenwm_msg outputs

Response structure:

{
  "Ok": {
    "Outputs": {
      "DP-1": {
        "name": "DP-1",
        "connected": true,
        "make": "ASUSTek COMPUTER INC",
        "model": "VG27AQML1A",
        "serial": "S9LMQS168079",
        "physical_size": [600, 340],
        "modes": [{"width": 2560, "height": 1440, "refresh_rate": 240001, "is_preferred": true}],
        "current_mode": 0,
        "refresh_rate": 240001,
        "x": 0, "y": 0,
        "width": 2560, "height": 1440,
        "scale": 1.0,
        "transform": "Normal"
      }
    }
  }
}

Note: make, model, and serial depend on whether your monitors expose EDID via the Wayland wl_output description. If they don't, these will show as "Unknown" / null.

`morgenwm_msg workspaces`

Returns all workspaces with their ID, name, output, and focus state.

morgenwm_msg workspaces

`morgenwm_msg windows`

Returns all managed windows with their ID, title, app-id, workspace, and focus state.

morgenwm_msg windows

`morgenwm_msg focused-window`

Returns the currently focused window (or null).

morgenwm_msg focused-window

`morgenwm_msg overview-state`

Returns whether the overview is currently open.

morgenwm_msg overview-state

`morgenwm_msg keyboard-layouts`

Returns the current keyboard layout configuration.

morgenwm_msg keyboard-layouts

Actions

Actions are sent as JSON objects with an "Action" key. Responses return {"Ok": "Handled"} on success.

All actions are also available via morgenwm_msg action <subcommand>.

Window Actions

# Close the focused window
morgenwm_msg action close-window

# Close a specific window by ID
morgenwm_msg action close-window --id 42

# Focus a specific window by ID
morgenwm_msg action focus-window --id 42

# Toggle fullscreen
morgenwm_msg action fullscreen-window

# Toggle floating
morgenwm_msg action toggle-window-floating

# Toggle overview
morgenwm_msg action toggle-overview

Workspace Actions

# Focus workspace by index (1-based)
morgenwm_msg action focus-workspace 3

# Focus next/previous workspace
morgenwm_msg action focus-workspace-up
morgenwm_msg action focus-workspace-down

# Set workspace name
morgenwm_msg action set-workspace-name --name "dev"

# Unset workspace name
morgenwm_msg action unset-workspace-name

# Focus column left/right
morgenwm_msg action focus-column-left
morgenwm_msg action focus-column-right
morgenwm_msg action focus-column-first
morgenwm_msg action focus-column-last

# Focus window up/down within frame
morgenwm_msg action focus-window-up
morgenwm_msg action focus-window-down

# Move column left/right
morgenwm_msg action move-column-left
morgenwm_msg action move-column-right

# Move window up/down
morgenwm_msg action move-window-up
morgenwm_msg action move-window-down
morgenwm_msg action move-window-left
morgenwm_msg action move-window-right

Spawn Actions

# Spawn a command (array form)
morgenwm_msg action spawn -- foot

# Spawn a shell command (string form)
morgenwm_msg action spawn-sh --command "echo hello"

Session Actions

# Quit MorgenWM (asks River to exit the session)
morgenwm_msg action quit

# Reload the config file from disk and reapply keybindings + keyboard layout
# live (same as saving the config file, but explicit). Useful after fixing a
# parse error that left the old config in place.
morgenwm_msg action reload-config

# Apply a layout template (replaces the current frame layout and spawns
# each leaf's command). See docs/templates.md for the template format.
morgenwm_msg action apply-template dev-layout

Event Stream

Subscribe to live state changes. The initial response contains the current state; subsequent lines are pushed as state changes occur.

morgenwm_msg event-stream

Events are JSON objects with one of these keys:

Event	Description
`WorkspacesChanged`	Workspace list changed (created, removed, renamed, focused)
`WindowsChanged`	Window list changed (opened, closed, moved, focused)
`OutputsChanged`	Output list changed (connected, disconnected, mode change)
`OverviewOpenedOrClosed`	Overview was toggled

Example: monitor events with jq

morgenwm_msg event-stream | jq --unbuffered '.'

Example: react to workspace changes

morgenwm_msg event-stream | while read -r line; do
  echo "$line" | jq -r 'select(.WorkspacesChanged) | .WorkspacesChanged.workspaces[] | "\(.id) \(.name // "")"'
done

Bar Integration

MorgenWM's Niri-compatible IPC means any bar that supports Niri will work.