hymission

hymission is a Hyprland plugin that provides a Mission Control-style overview with live compositor-side previews, scope-aware collection, trackpad gestures, and a workspace strip for active-workspace overview mode.

Inspired By Apple Mission Control

Referenced hyprexpo, hycov, and Hyprspace.

• Mission Control-style overview with animated window previews
• Scope control with default config scope, onlycurrentworkspace, and forceall
• Mouse, keyboard, and trackpad-driven overview interaction
• Optional selected-preview expansion with local push-away animation
• Gesture-only recommand mode for two-sided toggle gestures
• Workspace strip when the current overview scope shows only the active workspace
• Multi-monitor support
• Pinned-window, special-workspace, and scrolling-layout aware behavior
• Workspace-to-workspace overview transitions without showing the native workspace animation in the middle

hyprpm is the preferred user-facing install path in the Hyprland ecosystem.

hyprpm update
hyprpm add https://github.com/gfhdhytghd/hymission
hyprpm enable hymission
hyprpm reload

If you use Hyprland's permission system, you may need to allow hyprpm in your config:

hl.permission("/usr/(bin|local/bin)/hyprpm", "plugin", "allow")

Do not also manually hyprctl plugin load the same plugin if you manage it through hyprpm.

For local development, hymission uses CMake and outputs build-cmake/libhymission.so.

Requirements:

• Hyprland development headers for the exact Hyprland build you are running
• cmake
• pkg-config
• a C++23-capable compiler

nlohmann/json is bundled as a single header under src/vendor/ (v3.12.0), so no system package is required. Do not re-add find_package(nlohmann_json).

Build:

cmake -DCMAKE_BUILD_TYPE=Release -B build-cmake
cmake --build build-cmake -j"$(nproc)"
ctest --test-dir build-cmake --output-on-failure

Unload (optional): only needed if a previous copy is already loaded, so you start from a clean state. plugin not loaded is expected and harmless when a path was not the active copy.

hyprctl plugin unload "$(pwd)/build-cmake/libhymission.so"

If you previously built into a different directory, unload that path too, e.g. build/ or build-meson/.

Load the freshly built copy and confirm it is active:

hyprctl plugin load "$(pwd)/build-cmake/libhymission.so"
hyprctl plugin list

Build outputs:

• Plugin: build-cmake/libhymission.so
• Layout demo: build-cmake/hymission-layout-demo
• Layout test: build-cmake/hymission-mission-layout-test
• Logic test: build-cmake/hymission-overview-logic-test

hl.bind("SUPER + TAB", hl.plugin.hymission.toggle)
hl.bind("SUPER + SHIFT + TAB", function()
    hl.plugin.hymission.toggle("reverse")
end)
hl.bind("SUPER + CTRL + TAB", hl.plugin.hymission.close)
hl.bind("SUPER + C", function()
    hl.plugin.hymission.toggle("onlycurrentworkspace")
end)
hl.bind("SUPER + A", function()
    hl.plugin.hymission.toggle("forceall")
end)
hl.bind("SUPER + M", hl.plugin.hymission.debug_current_layout)

Lua configuration should normally call the native plugin functions shown below. The colon-form names are the corresponding legacy dispatchers for non-Lua configuration.

Toggle switch mode only changes hymission:toggle; open, close, and gesture paths keep their normal behavior.

With a binding such as hl.bind("SUPER + TAB", hl.plugin.hymission.toggle) and:

hl.config({
    plugin = {
        hymission = {
            toggle_switch_mode = 1,
            switch_toggle_auto_next = 1,
            switch_release_key = "Super_L",
        },
    },
})

This mode is intended for modifier-backed bindings such as ALT+TAB and SUPER+TAB.

Hymission exposes native plugin functions under hl.plugin.hymission:

hl.bind("SUPER + TAB", hl.plugin.hymission.toggle)
hl.bind("SUPER + A", function()
    hl.plugin.hymission.toggle("forceall")
end)
hl.bind("SUPER + S", function()
    hl.plugin.hymission.open("onlycurrentworkspace")
end)
hl.bind("SUPER + Escape", hl.plugin.hymission.close)
hl.bind("SUPER + O", function()
    hl.plugin.hymission.fullscreen({ mode = "maximized", action = "toggle" })
end)

Available functions:

• hl.plugin.hymission.toggle(args?)
• hl.plugin.hymission.open(args?)
• hl.plugin.hymission.close()
• hl.plugin.hymission.fullscreen({ mode = "fullscreen"|"maximized", action = "toggle"|"set"|"unset" })
• hl.plugin.hymission.debug_current_layout()
• hl.plugin.hymission.dispatch(name, args?)
• hl.plugin.hymission.gesture(table|string, disable_inhibit?)

toggle and open accept the optional scope arguments forceall and onlycurrentworkspace. Only toggle additionally accepts reverse as a switch-session direction modifier.

Register Hymission gestures through hl.plugin.hymission.gesture(...) instead of hl.gesture({ action = function() ... end }) when you want continuous overview progress:

hl.plugin.hymission.gesture({
    fingers = 4,
    direction = "vertical",
    action = "toggle",
    args = "forceall",
})

hl.plugin.hymission.gesture({
    fingers = 4,
    direction = "vertical",
    action = "toggle",
    recommand = true,
})

hl.plugin.hymission.gesture({
    fingers = 4,
    direction = "vertical",
    action = "open",
    scope = "onlycurrentworkspace",
})

hl.plugin.hymission.gesture({
    fingers = 3,
    direction = "horizontal",
    action = "scroll",
    mode = "layout",
})

-- Native alternative:
-- hl.gesture({ fingers = 3, direction = "horizontal", action = "scroll_move" })

hl.plugin.hymission.gesture({
    fingers = 3,
    direction = "vertical",
    action = "workspace",
})

Optional gesture fields are mods, scale, and disable_inhibit.

Gesture notes:

• vertical and horizontal are supported for plugin-managed overview gestures; hymission:scroll,layout also supports swipe
• default gesture semantics are state-aware: hidden overview opens in the configured direction, and visible hymission:toggle,* overview can close in either swipe direction
• recommand is gesture-only and is only valid with hymission:toggle
• scrolling layout movement supports both hymission:scroll,layout and Hyprland's official scrollMove / Lua scroll_move
• workspace swipes should use hl.plugin.hymission.gesture({ ..., action = "workspace" }); Hymission already intercepts that path while overview is visible
• in recommand mode, one side opens forceall and the other side opens onlycurrentworkspace
• switching from one visible recommand side to the other only works in the side-changing direction; it must pass through hidden state and then cross a small transfer gap before the opposite side starts opening
• swiping the other visible recommand direction only exits overview back to hidden and does not continue into the opposite side
• a gesture that started from hidden can still be pulled back to cancel, but it cannot become a new visible-start close/transfer gesture until you lift and swipe again
• release still uses a 50% + velocity commit rule

All user-facing settings live under plugin.hymission in hl.config.

Example:

hl.config({
    plugin = {
        hymission = {
            -- Layout: common geometry and sizing
            outer_padding_top = 92,
            outer_padding_right = 32,
            outer_padding_bottom = 32,
            outer_padding_left = 32,
            row_spacing = 32,
            column_spacing = 32,
            min_window_length = 120,
            min_preview_short_edge = 32,
            small_window_boost = 1.35,
            max_preview_scale = 0.95,
            workspace_overview_max_preview_scale = 0.95,
            min_slot_scale = 0.10,
            one_workspace_per_row = 0,

            -- Layout: engine selection and per-engine settings
            layout_engine = "grid",
            layout_engine_forceall = "",
            layout_engine_all = "",
            layout_engine_onlycurrentworkspace = "",
            layout_scale_weight = 1.0,
            layout_space_weight = 0.10,
            natural_scale_flex = 0.22,

            -- Behavior: workspace scope and transitions
            multi_workspace_sort_recent_first = 1,
            only_active_workspace = 0,
            only_active_monitor = 0,
            show_special = 0,
            workspace_change_keeps_overview = 1,

            -- Behavior: hover and selection
            expand_selected_window = 1,
            hover_expand_scale = 1.18,
            overview_focus_follows_mouse = 1,
            show_focus_indicator = 0,
            grouped_windows_policy = "expanded",
            grouped_windows_collapsed_labels = 1,
            grouped_windows_collapsed_scroll = 1,

            -- Animation: hover relayout
            hover_relayout_animation = "",
            hover_relayout_duration = 140,
            hover_relayout_curve = "ease_out_cubic",

            -- Behavior: toggle switch and gestures
            toggle_switch_mode = 0,
            switch_toggle_auto_next = 1,
            switch_release_key = "Super_L",
            gesture_invert_vertical = 0,

            -- Niri mode
            niri_mode = 0,
            niri_scroll_pixels_per_delta = 1.0,
            niri_workspace_scale = 1.0,
            niri_scrolling_preview_gap = 0,

            -- Workspace strip and bar
            workspace_strip_anchor = "left",
            workspace_strip_empty_mode = "existing",
            workspace_strip_thickness = 160,
            workspace_strip_gap = 24,
            hide_bar_when_strip = 1,
            hide_hyprbars_during_overview = 0,
            bar_single_mission_control = 0,
            hide_bar_animation = 1,
            hide_bar_animation_blur = 1,
            hide_bar_animation_move_multiplier = 0.8,
            hide_bar_animation_scale_divisor = 1.1,
            hide_bar_animation_alpha_end = 0,

            -- Label picking and window controls
            pick_labels_enabled = 0,
            pick_labels_show = 1,
            pick_labels_mode = "sequential",
            pick_labels_direct_activate = 0,
            window_decoration_enabled = 1,
            close_button_enabled = 0,
            close_button_size = 18,
            close_button_inset = 0,

            -- Appearance and color customization
            backdrop_blur = 0,
            backdrop_color = "rgba(00000000)",
            focus_hover_color = "rgba(f2f7ff8c)",
            focus_selected_color = "rgba(3dc7fff2)",
            focus_hover_thickness = 2,
            focus_selected_thickness = 4,
            workspace_strip_inactive_tint_color = "rgba(00000000)",

            -- Debug
            debug_logs = 0,
            debug_surface_logs = 0,
        },
    }
})

An empty scope override inherits layout_engine.

The natural engine can also use the row-search path as an emergency fallback, so these weights still affect that fallback.

The natural engine tries to preserve original window positions while removing overlap. It attempts every window count before falling back to row search.

In multi-workspace overview, hover-driven real focus may still cross workspaces, but the overview grid stays anchored instead of rebuilding on every workspace change. In active-workspace overview, workspace changes use the dedicated overview-to-overview transition path.

Toggle switch mode keeps the normal hover semantics: with overview_focus_follows_mouse = 1, moving the pointer can retarget the final selection committed when the modifier is released.

With niri_mode = 1, the strip stays in the configured edge band and the main overview remains the scaled window overview. The strip uses monitor-aspect workspace thumbnails, centers the active workspace on open, and allows the thumbnail list to overflow instead of shrinking every workspace into view. Tiled scrolling layout previews use workspace_overview_max_preview_scale on the non-scrolling axis and may overflow along the scrolling axis, so gesture panning moves the centered row or column. Both hymission:scroll,layout and Lua scroll_move can scroll the layout inside the niri overview; workspace switching continues to use hl.plugin.hymission.gesture({ ..., action = "workspace" }).

Hymission suppresses Hyprland's native groupbar only while overview is visible. In expanded mode, inactive group members ignore Hyprland's group-layout alpha inside overview while retaining their normal rule and fade opacity. Dragging any group member moves the whole group: all member previews shrink into a bounded stack under the pointer, then return together or animate into the target workspace thumbnail. Group order, membership, and lock state are preserved.

• In sequential mode, past the 9th window a letter key (A-Z) arms a ~1.5s prefix waiting for its digit (e.g. A then 2 picks A2); any other key cancels the prefix without losing its own normal effect (e.g. Esc still closes overview).
• In spatial mode, key positions and activation use physical ANSI alphanumeric and punctuation keycodes (` 1-0 - = Q-P [ ] \\ A-L ; ' Z-M , . /), while badge text follows the active keyboard's current XKB layout automatically (using its unshifted level, so Shift/Caps Lock do not change the badge). A shared primary waits up to ~1.5s for the same key (center) or an adjacent key in the labelled direction; equivalent adjacent keys in that direction are also accepted.

The workspace strip is shown when the current overview scope displays only the active workspace. By default it only shows real workspaces plus the trailing new-workspace card. In continuous mode, synthetic empty workspaces progressively expose numbered gaps one slot at a time and render the monitor background/wallpaper when available.

Color values below use Hyprland rgba(rrggbbaa) syntax.

Label chips reuse the close-button background, glyph, and size settings.

Leave bar_single_mission_control = 0 if you want hyprland/workspaces to keep showing the usual numbered workspaces.

If you explicitly want hyprland/workspaces to collapse to a single Mission Control button while multi-workspace overview is visible:

1. Set bar_single_mission_control = 1 in hl.config({ plugin = { hymission = { ... } } }).
2. Add an ignore-workspaces rule that hides the plugin's temporary names:

"hyprland/workspaces": {
  "all-outputs": true,
  "disable-scroll": true,
  "on-click": "activate",
  "persistent_workspaces": {},
  "ignore-workspaces": ["^__hymission_hidden__:"]
}

This keeps normal workspace names untouched outside overview. While overview is open, the anchor workspace remains Mission Control and the other regular overview workspaces are renamed to the hidden prefix so Waybar drops them from the module.

Useful commands:

./build-cmake/hymission-layout-demo
./build-cmake/hymission-layout-demo --list-scenes
./build-cmake/hymission-layout-demo --scene forceall --engine natural --output /tmp/hymission-forceall-natural.svg
./build-cmake/hymission-layout-demo --scene forceall --engine grid --output /tmp/hymission-forceall-grid.svg
./build-cmake/hymission-layout-demo --stress 5000 --seed 1 --output /tmp/hymission-stress-worst.svg
./build-cmake/hymission-mission-layout-test
./build-cmake/hymission-overview-logic-test
hyprctl dispatch hymission:debug_current_layout

hymission-layout-demo runs the geometry solver without loading the Hyprland plugin. In SVG output, dashed rectangles are source window geometry and solid rectangles are overview targets. Built-in scenes include forceall, default, stacked, right-biased, and workspace-rows. It also reports gravity, heatmap balance, motion, and x/y inversion metrics; SVG output draws heat cells, the screen center, and the target-area centroid. --stress generates random pathological scenes and writes the worst-scoring case for solver tuning.

Project docs:

• docs/spec.md: behavior and user-facing semantics
• docs/architecture.md: controller, hooks, and state-machine structure
• docs/research.md: layout tradeoffs and prior-art notes
• docs/workspace_strip_plan.md: strip-specific implementation planning
• docs/todo.md: current gaps and next steps
• devlog/: implementation notes for recent iterations

• The repository includes a root hyprpm.toml manifest, which is expected by hyprpm.
• For inclusion in the official hyprland-plugins repository, Hyprland asks plugin authors to coordinate with the repository maintainer first.