Complete List of Hyprland IPC Socket Events: Reference and Usage Guide

Hyprland exposes compositor state changes through a Unix-domain socket at .socket2.sock, emitting over 30 distinct event types—including workspace, window, monitor, and input events—in a event>>payload format.

The Hyprland Wayland compositor (hyprwm/Hyprland) provides an IPC socket that allows external programs to react to compositor state changes in real-time. Every event follows a standardized format defined in the CEventManager class, making it possible to build status bars, notification daemons, and automation scripts that respond instantly to window management actions.

How the Hyprland IPC Socket Works

Hyprland's IPC mechanism centers around the CEventManager singleton (g_pEventManager), defined in src/managers/EventManager.hpp. When the compositor triggers a state change, it constructs a SHyprIPCEvent struct containing the event name and data payload:

struct SHyprIPCEvent {
    std::string event;   // e.g. "workspace"
    std::string data;    // payload, format defined per-event
};

The manager formats each event as <event>>[payload]\n in CEventManager::formatEvent (src/managers/EventManager.cpp, lines 26-31). Payloads are truncated to 1 KB, with internal newlines replaced by spaces to ensure single-line messages. The socket itself is created at g_pCompositor->m_instancePath + "/.socket2.sock" (see the constructor in src/managers/EventManager.cpp, lines 14-30).

Clients connecting to this non-blocking Unix socket receive a stream of newline-terminated messages. The manager maintains a queue of up to 64 events per client (MAX_QUEUED_EVENTS in src/managers/EventManager.cpp, lines 69-78); exceeding this limit causes the client to be dropped.

Complete List of Available IPC Events

The compositor emits events from multiple subsystems. Each event name is broadcast exactly as shown, followed by the specified payload format.

Workspace Events

Emitted by src/state/WorkspacePlacementController.cpp and src/desktop/Workspace.cpp:

• workspace / workspacev2 — Workspace changed. Payload: name (v1) or id,name (v2). Source: lines 224-226.
• moveworkspace / moveworkspacev2 — Workspace moved to another monitor. Payload: srcWS,dstMonitor (v1) or srcID,srcWS,dstMonitor (v2). Source: lines 230-233.
• createworkspace / createworkspacev2 — New workspace created. Payload: name (v1) or id,name (v2). Source: src/desktop/Workspace.cpp, lines 72-73.
• destroyworkspace / destroyworkspacev2 — Workspace destroyed. Payload: name (v1) or id,name (v2). Source: lines 81-82.
• renameworkspace — Workspace renamed. Payload: id,newName. Source: line 543.
• changeworkspaceid — Workspace ID modified. Payload: oldID,newID. Source: line 560.

Monitor Events

Emitted by src/output/Monitor.cpp and src/desktop/state/FocusState.cpp:

• monitoradded / monitoraddedv2 — New output connected. Payload: name (v1) or id,name,shortDesc (v2). Source: Monitor.cpp, lines 387-388.
• monitorremoved / monitorremovedv2 — Output disconnected. Payload: name (v1) or id,name,shortDesc (v2). Source: lines 397-398.
• focusedmon / focusedmonv2 — Focus changed to different monitor. Payload: monitor,workspaceName (v1) or monitor,workspaceID (v2). Source: FocusState.cpp, lines 287-288.

Window and Layer Events

Emitted by src/desktop/view/Window.cpp, src/desktop/view/LayerSurface.cpp, and related files:

• openwindow — Window created. Payload: XID,workspace,class,title. Source: Window.cpp, lines 2369-2370.
• closewindow — Window closed. Payload: XID. Source: line 2574.
• movewindow / movewindowv2 — Window moved to different workspace. Payload: XID,workspaceName (v1) or XID,workspaceID,workspaceName (v2). Source: lines 579-580.
• windowtitle / windowtitlev2 — Window title changed. Payload: XID (v1) or XID,title (v2). Source: lines 1452-1453.
• activewindow / activewindowv2 — Focus changed to different window. Payload: class,title (v1) or XID (v2). Source: FocusState.cpp, lines 209-210.
• urgent — Window demands attention. Payload: XID. Source: Window.cpp, line 1371.
• fullscreen — Fullscreen state toggled. Payload: 0 (false) or 1 (true). Source: src/managers/fullscreen/FullscreenController.cpp, line 482.
• changefloatingmode — Floating mode toggled. Payload: XID,0|1. Source: src/layout/LayoutManager.cpp, lines 47-50.
• togglegroup — Window entered or left a group. Payload: 1|0,XID (enter/leave). Source: src/desktop/view/Group.cpp, lines 66-82.
• openlayer / closelayer — Layer surface (like waybar or notifications) opened or closed. Payload: layerNamespace. Source: src/desktop/view/LayerSurface.cpp, lines 218-227.
• minimized — Wayland toplevel minimized state changed. Payload: XID,1|0 (minimized/restored). Source: src/protocols/ForeignToplevelWlr.cpp, lines 126-138.

Input and Layout Events

Emitted by src/managers/input/InputManager.cpp and src/config/shared/actions/ConfigActions.cpp:

• kill — Window kill signal sent. Payload: XID. Source: InputManager.cpp, line 947.
• activelayout — Keyboard layout changed. Payload: keyboard,layoutName. Source: lines 1183-1184.
• pin — Window pinned state toggled. Payload: XID,0|1. Source: ConfigActions.cpp, line 265.
• submap — Keymap submap changed. Payload: empty string, or name of the new submap. Source: lines 1664-1672.
• lockgroups — Group locking toggled. Payload: 1 or 0. Source: line 1277.

System and Configuration Events

• configreloaded — Configuration file reloaded. Payload: (empty). Source: src/config/lua/ConfigManager.cpp, line 848.
• bell — XDG notification bell triggered. Payload: (none). Source: src/protocols/XDGBell.cpp, lines 17-47.
• screencast / screencastv2 — Screensharing started or stopped. Payload: 1|0,type (v1) or 1|0,type,name (v2). Source: src/managers/screenshare/ScreenshareSession.cpp, lines 140-148.
• custom — User-defined event emitted via configuration. Payload: arbitrary string supplied by the user. Source: ConfigActions.cpp, line 1266.

Listening to IPC Events

You can monitor these events using standard Unix socket tools or the built-in hyprctl utility.

Using netcat (nc)

Connect directly to the socket path, which resides under $XDG_RUNTIME_DIR/hypr/:

# Print raw events as they arrive

socket="${XDG_RUNTIME_DIR}/hypr/.socket2.sock"
nc -U "$socket"

Parsing Events in Shell Scripts

Parse the event>>payload format in Bash to trigger specific actions:

#!/usr/bin/env bash
socket="${XDG_RUNTIME_DIR}/hypr/.socket2.sock"

while IFS= read -r line; do
    # Split on ">>"

    IFS='>>' read -r ev payload <<< "$line"
    case "$ev" in
        workspace)    notify-send "Workspace" "Changed to: $payload" ;;
        activewindow) echo "Active class: ${payload%%,*}" ;;
        monitoradded) echo "New monitor: $payload" ;;
        urgent)       notify-send "Urgent window" "$payload" ;;
    esac
done < <(nc -U "$socket")

Using hyprctl

Hyprland ships with hyprctl, which includes a built-in events command:

# Stream all events with automatic socket detection

hyprctl events

To query specific state information rather than streaming events, use the request socket (.socket.sock), though this returns static data rather than event streams:

# Get current active window class

echo "activewindow>>" | nc -U "${XDG_RUNTIME_DIR}/hypr/.socket.sock" | cut -d',' -f1

Summary

• Hyprland IPC events flow through a Unix socket at .socket2.sock managed by CEventManager in src/managers/EventManager.cpp.
• Over 30 event types cover workspaces, monitors, windows, layers, input devices, and configuration changes.
• Events follow the format event>>payload\n, with payloads truncated to 1 KB and newlines sanitized.
• The event queue limits clients to 64 buffered messages; overflow disconnects the client.
• Usage requires parsing the stream with tools like nc, socat, or the built-in hyprctl events command.

Frequently Asked Questions

What is the difference between v1 and v2 event versions?

V2 events include numerical IDs alongside string names. For example, workspace sends only the workspace name, while workspacev2 sends id,name. Similarly, activewindowv2 sends the window's XID (numerical identifier) instead of the class and title strings. Use v2 events when your script needs stable identifiers that persist across renaming operations.

Where is the IPC socket located?

The socket path is constructed at runtime as $XDG_RUNTIME_DIR/hypr/.socket2.sock. The exact directory includes the compositor instance name, but under standard configurations, this resolves to /run/user/1000/hypr/.socket2.sock (where 1000 is your UID). The hyprctl utility automatically detects this path, or you can locate it via the $HYPRLAND_INSTANCE_SIGNATURE environment variable.

Can I emit custom events through the IPC socket?

Yes, using the custom event type. You can trigger custom events from Hyprland configuration files or keybindings using the ipc dispatcher, which accepts an arbitrary string payload. These events broadcast to all connected IPC clients with the event name custom and your supplied data, enabling integration between Hyprland bindings and external scripts.

What happens if my script cannot keep up with event production?

The Event Manager drops clients that exceed the 64-event buffer. If your script blocks or processes events too slowly, once the queue fills, Hyprland disconnects that client to prevent memory bloat. For reliable operation, ensure your event loop reads continuously or runs in a separate thread, and consider using hyprctl events which handles buffering internally.

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