Hyprtasking

Powerful workspace management plugin, packed with features.

[!Important]

Supports Hyprland releases v0.46.2-v0.56.2.

https://github.com/user-attachments/assets/8d6cdfd2-2b17-4240-a117-1dbd2231ed4e

Jump To Installation

See Configuration

Roadmap

Installation

Hyprpm

hyprpm add https://github.com/raybbian/hyprtasking
hyprpm enable hyprtasking

Hyprland plugins must match the compositor ABI exactly. For tagged Hyprland releases, Hyprpm uses the compatibility pins in hyprpm.toml to select the corresponding hyprtasking revision.

Nix

Add hyprtasking to your flake inputs

# flake.nix
{
  inputs = {
    hyprland.url = "github:hyprwm/Hyprland/v0.56.0";

    hyprtasking = {
      url = "github:raybbian/hyprtasking";
      inputs.hyprland.follows = "hyprland";
    };
  };
  # ...
}

Include the plugin in the hyprland home manager options

# home.nix
{ inputs, pkgs, ... }:
{
  wayland.windowManager.hyprland = {
    plugins = [
      inputs.hyprtasking.packages.${pkgs.system}.hyprtasking
    ];
  }
}

Manual

To build, install Hyprland headers from the exact compositor commit you are running and then:

meson setup build
cd build && meson compile

Then use hyprctl plugin load to load the absolute path to the .so file:

hyprctl plugin load "$(realpath libhyprtasking.so)"

Usage

Opening Overview

Bind hyprtasking:toggle, all to a keybind to open/close the overlay on all monitors.
Bind hyprtasking:toggle, cursor to a keybind to open the overlay on one monitor and close on all monitors.
Swipe up/down on a touchpad device to open/close the overlay on one monitor.
See below for configuration options.

Interaction

Workspace Transitioning:
- Open the overlay, then use right click to switch to a workspace
- Use the directional dispatchers hyprtasking:move to switch to a workspace
- With jump.enabled enabled, press the label shown over a workspace to jump to it (1-9, 0, then a-z). Set jump.show_workspace_names to display workspace names such as A1 instead of the keyboard jump labels.
Window management:
- Left click to drag and drop windows around

Configuration

Example below:

hl.bind("SUPER + TAB", function() hl.plugin.hyprtasking.toggle("cursor") end)
hl.bind("SUPER + SPACE", function() hl.plugin.hyprtasking.toggle("all") end)

-- escape closes the overview if it's open
hl.bind("escape", function()
  if hl.plugin.hyprtasking.is_active() then
    hl.plugin.hyprtasking.toggle('all')
  end
end, { non_consuming = true })

hl.bind("SUPER + X", function() hl.plugin.hyprtasking.killhovered() end)

hl.bind("SUPER + H", function() hl.plugin.hyprtasking.move("left") end)
hl.bind("SUPER + J", function() hl.plugin.hyprtasking.move("down") end)
hl.bind("SUPER + K", function() hl.plugin.hyprtasking.move("up") end)
hl.bind("SUPER + L", function() hl.plugin.hyprtasking.move("right") end)

hl.bind("SUPER + A", function() hl.plugin.hyprtasking.move("out") end)
hl.bind("SUPER + SHIFT + A", function() hl.plugin.hyprtasking.movewindow("out") end)

hl.bind("SUPER + CTRL + 1", function() hl.plugin.hyprtasking.setlayer(1) end)
hl.bind("SUPER + CTRL + 2", function() hl.plugin.hyprtasking.setlayer(2) end)

hl.config({
  plugin = {
    hyprtasking = {
      layout = "grid",

      gap_size = 10,
      bg_color = 0xff26233a,
      border_size = 2,
      exit_on_hovered = false,
      warp_on_move_window = 1,
      close_overview_on_reload = false,

      -- for other mouse buttons see <linux/input-event-codes.h>
      drag_button = 0x110,   -- left mouse button
      select_button = 0x111, -- right mouse button

      jump = {
        enabled = false,
        show_workspace_names = false,
        label_color = 0xffffffff,
        label_background = 0x000000cc,
        label_size = 32,
      },

      gestures = {
        enabled = true,
        move_fingers = 3,
        move_distance = 300,
        open_fingers = 4,
        open_distance = 300,
        open_positive = true,
      },

      grid = {
        rows = 3,
        cols = 3,
        loop = false,
        layers = 2,
        loop_layers = true,
        gaps_use_aspect_ratio = true,
      },

      linear = {
        top = false,
        height = 400,
        scroll_speed = 1.0,
        blur = false,
      }
    }
  },
})

Click here to see the old hyprlang syntax

bind = SUPER, tab, hyprtasking:toggle, cursor
bind = SUPER, space, hyprtasking:toggle, all
# NOTE: the lack of a comma after hyprtasking:toggle!
bind = , escape, hyprtasking:if_active, hyprtasking:toggle cursor


bind = SUPER, X, hyprtasking:killhovered

bind = SUPER, H, hyprtasking:move, left
bind = SUPER, J, hyprtasking:move, down
bind = SUPER, K, hyprtasking:move, up
bind = SUPER, L, hyprtasking:move, right

bind = SUPER, A, hyprtasking:move, out
bind = SUPER SHIFT, A, hyprtasking:movewindow, out

bind = SUPER CTRL, 1, hyprtasking:setlayer, 1
bind = SUPER CTRL, 2, hyprtasking:setlayer, 2

plugin {
    hyprtasking {
        layout = grid

        gap_size = 10
        bg_color = 0xff26233a
        border_size = 2
        exit_on_hovered = false
        warp_on_move_window = 1
        close_overview_on_reload = false

        drag_button = 0x110 # left mouse button
        select_button = 0x111 # right mouse button
        # for other mouse buttons see <linux/input-event-codes.h>

        jump {
            enabled = false
            label_color = 0xffffffff
            label_background = 0x000000cc
            label_size = 32
        }

        gestures {
            enabled = true
            move_fingers = 3
            move_distance = 300
            open_fingers = 4
            open_distance = 300
            open_positive = true
        }

        grid {
            rows = 3
            cols = 3
            loop = false
            layers = 2
            loop_layers = true
            gaps_use_aspect_ratio = true
        }

        linear {
            top = false
            height = 400
            scroll_speed = 1.0
            blur = false
        }
    }
}

Dispatchers

hyprtasking:if_active, ARG takes in a dispatch command (one that would be used after hyprctl dispatch ...) that will be dispatched only if the cursor overview is active.
- Allows you to use e.g. escape to close the overview when it is active. See the example config for more info.
hyprtasking:if_not_active, ARG same as above, but if the overview is not active.
hyprtasking:toggle [, ARG] takes 1 optional argument that is either cursor or all
- if the argument is all, then
  - if all overviews are hidden, then all overviews will be shown
  - otherwise all overviews will be hidden
- if the argument is cursor or no argument is given, then
  - if current monitor's overview is hidden, then it will be shown
  - otherwise all overviews will be hidden
hyprtasking:move, ARG takes in 1 argument that is one of up, down, left, right, in, out
- when dispatched, hyprtasking will switch workspaces with a nice animation
hyprtasking:movewindow, ARG takes in 1 argument that is one of up, down, left, right, in, out
- when dispatched, hyprtasking will 1. move the hovered window to the workspace in the given direction relative to the window, and 2. switch to that workspace.

Click here to see the coordinate space

hyprtasking:setlayer, ARG takes in 1 optional argument that specifies the direction of movement across layers.
- if provided, the argument has to start with + or - to take effect. For example: +1, -3
- no arguments has the same effect as +1
- when dispatched, hyprtasking will move you through the layers in the specified direction
- if plugin option grid:loop_layers is enabled, will loop the layers if next requested layer is out of bounds (not in the range form 0 to grid:layers)
hyprtasking:setlayerwindow, ARG takes in 1 optional argument that specifies the direction of movement across layers.
- when dispatched, hyprtasking will do the same as hyprtasking:setlayer, ARG and also move the window through layers
hyprtasking:killhovered behaves similarly to the standard killactive dispatcher with focus on hover
- when dispatched, hyprtasking will close the currently hovered window, useful when the overview is active.
- this dispatcher is designed to replace hl.dsp.close(), it will work even when the overview is not active.

Config Options

All options are prefixed with plugin:hyprtasking:.

Option	Type	Description	Default
`layout`	`string`	The layout to use, either `grid` or `linear`	`grid`
`bg_color`	`int`	The color of the background of the overlay	`0x000000FF`
`gap_size`	`float`	The width in logical pixels of the gaps between workspaces	`8.f`
`border_size`	`float`	The width in logical pixels of the borders around workspaces	`4.f`
`exit_on_hovered`	`int`	If true, hiding the workspace will exit to the hovered workspace instead of the active workspace.	`false`
`warp_on_move_window`	`int`	Works the same as `cursor:warp_on_change_workspace` (see wiki) but with the `hyprtasking:movewindow` dispatcher. `cursor:warp_on_change_workspace` works only with the `hyprtasking:move` dispatcher	`1`
`close_overview_on_reload`	`int`	Whether to close the overview if its layout type did not change after a Hyprland config reload	`true`
`drag_button`	`int`	The mouse button to use to drag windows around	`0x110`
`select_button`	`int`	The mouse button to use to select a workspace	`0x111`
`gestures:enabled`	`int`	Whether or not to enable gestures	`true`
`gestures:move_fingers`	`int`	The number of fingers to use for the "move" gesture	`3`
`gestures:move_distance`	`float`	How large of a swipe on the touchpad corresponds to the width of a workspace	`300.f`
`gestures:open_fingers`	`int`	The number of fingers to use for the "open" gesture	`4`
`gestures:open_distance`	`float`	How large of a swipe on the touchpad is needed for the "open" gesture	`300.f`
`gestures:open_positive`	`int`	`true` if swiping up should open the overlay, `false` otherwise	`true`
`grid:rows`	`int`	The number of rows to display on the grid overlay	`3`
`grid:cols`	`int`	The number of columns to display on the grid overlay	`3`
`grid:loop`	`int`	When enabled, moving right at the far right of the grid will wrap around to the leftmost workspace, etc.	`false`
`grid:layers`	`int`	The number of layers for grid layout, the third dimension	`1`
`grid:loop_layers`	`int`	When enabled, moving back on the first layer will wrap around to the last layer. The reverse also works	`true`
`grid:gaps_use_aspect_ratio`	`int`	When enabled, vertical gaps will be scaled to match the monitor's aspect ratio	`false`
`linear:top`	`int`	Whether or not to position the overview on top of the screen	`false`
`linear:blur`	`int`	Whether or not to blur the dimmed area	`true`
`linear:height`	`float`	The height of the linear overlay in logical pixels	`300.f`
`linear:scroll_speed`	`float`	Scroll speed modifier. Set negative to flip direction	`1.f`

^{FYI, "ARG" does not refer to any minecraft ARG. Why would you even ask that?
Eww}