---
name: hermes-hyprland
description: Controls Hyprland window management, workspaces, and window states using hyprctl dispatch commands.
version: 0.0.1
author: sortedcord
metadata:
  hermes:
    tags: [system, wm, linux, automation]
    requires_toolsets: [terminal]
    requires_tools: [bash]
---

# Hyprland Window Manager Control Skill

## When to Use

Use this skill when the user requests desktop layout changes, window manipulation, workspace switching, or diagnostic checks on open windows in their Hyprland environment.

## Procedure

### 1. Workspace Navigation

When asked to switch workspaces, move focus, or jump to a specific screen:

- Run the workspace dispatcher command:

```bash
  hyprctl dispatch 'hl.dsp.focus({ workspace = "<WORKSPACE_NUMBER>" })'
```

### 2. Window Information Gathering

When asked to list windows, find a specific application, or gather metadata:

Use hyprctl clients (or your active layout command) to fetch window lists.

You can pipe to grep to isolate fields like class, title, or workspace. For example:

```

  hyprctl clients | grep -E "Window|workspace|class|title"
```

3. Moving and Manipulating Windows
   When managing the active window's position, size, or target desktop:

Directional Move: To push a window left, right, up, or down:

```

  hyprctl dispatch 'hl.dsp.window.move({ direction = "<left|right|up|down>" })'
```

Move to Workspace: To send a window to another desktop:

```
  hyprctl dispatch 'hl.dsp.window.move({ workspace = <WORKSPACE_NUMBER> })'
```

Fullscreen: To toggle fullscreen on the current window:

```
hyprctl dispatch 'hl.dsp.window.fullscreen()'
```

### 4. Focus Window by Exact Address

When a specific window address (e.g., 0x55e07fc3f930) is targeted:

- Prefix the raw hexadecimal string with `address:0x` inside the window object.
- Execute the command:

  ```bash
  hyprctl dispatch 'hl.dsp.focus({ window = "address:0x<HEX_ADDRESS>" })'
  ```

### Pitfalls

String Quoting: Ensure that nested single and double quotes inside hyprctl dispatch arguments do not break shell syntax execution.

Dynamic Workspaces: If a workspace doesn't exist yet, Hyprland will typically create it on the fly. No need for explicit verification.