{"id":50543826,"url":"https://github.com/colonelpanic8/hyprwinview","last_synced_at":"2026-06-03T22:01:52.782Z","repository":{"id":354750451,"uuid":"1224964366","full_name":"colonelpanic8/hyprwinview","owner":"colonelpanic8","description":"Experimental Hyprland window overview plugin","archived":false,"fork":false,"pushed_at":"2026-05-07T23:22:12.000Z","size":12281,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-08T01:27:28.759Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/colonelpanic8.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-29T20:08:08.000Z","updated_at":"2026-05-07T23:22:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/colonelpanic8/hyprwinview","commit_stats":null,"previous_names":["colonelpanic8/hyprwinview"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/colonelpanic8/hyprwinview","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colonelpanic8%2Fhyprwinview","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colonelpanic8%2Fhyprwinview/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colonelpanic8%2Fhyprwinview/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colonelpanic8%2Fhyprwinview/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/colonelpanic8","download_url":"https://codeload.github.com/colonelpanic8/hyprwinview/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colonelpanic8%2Fhyprwinview/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33881107,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-03T22:01:51.988Z","updated_at":"2026-06-03T22:01:52.766Z","avatar_url":"https://github.com/colonelpanic8.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hyprwinview\n\n`hyprwinview` is an experimental Hyprland plugin that shows an overview of open\nwindows regardless of which workspace they are on.\n\nThe current version is a first working foundation:\n\n- snapshots mapped windows into an overview grid\n- sizes the grid from window count and monitor aspect ratio\n- focuses the hovered window\n- can bring the hovered window to the current workspace before focusing it\n- supports keyboard navigation while the overview is active\n- shows window title/class labels and supports type-to-filter narrowing\n\n## Demo\n\n[![hyprwinview type-to-filter demo](media/reddit/hyprwinview-real-incremental-filter-spo-select.png)](media/reddit/hyprwinview-real-incremental-filter-spo-select.png)\n\nThe demo opens the overview, narrows the window list by typing `spo`, and\nselects the Spotify window. `Ctrl+b` can also bring a matching window from\nanother workspace into the current workspace.\n\n## Build\n\n```sh\nnix build\n```\n\nThe plugin is built at:\n\n```sh\nresult/lib/libhyprwinview.so\n```\n\nFor development:\n\n```sh\ndirenv allow\n```\n\n## Install With hyprpm\n\n```sh\nhyprpm add https://github.com/colonelpanic8/hyprwinview\nhyprpm enable hyprwinview\nhyprpm reload\n```\n\nOn Nix systems, hyprpm will use this repository's flake development shell by\ndefault. Use `hyprpm --no-nix add ...` only when the system environment already\nprovides Hyprland headers and the build dependencies listed in\n`CMakeLists.txt`.\n\n## Hyprland Lua Config\n\nLoad the plugin:\n\n```lua\nhl.exec_once(\"hyprctl plugin load /path/to/libhyprwinview.so\")\n```\n\nExample bindings:\n\n```lua\nhl.bind(\"SUPER + Tab\", hl.dsp.exec_cmd(\"hyprctl dispatch hyprwinview:overview toggle\"))\nhl.bind(\"SUPER + SHIFT + Tab\", hl.dsp.exec_cmd(\"hyprctl dispatch hyprwinview:overview toggle other-workspaces\"))\nhl.bind(\"SUPER + Return\", hl.dsp.exec_cmd(\"hyprctl dispatch hyprwinview:overview select\"))\nhl.bind(\"SUPER + SHIFT + Return\", hl.dsp.exec_cmd(\"hyprctl dispatch hyprwinview:overview bring\"))\nhl.bind(\"SUPER + Escape\", hl.dsp.exec_cmd(\"hyprctl dispatch hyprwinview:overview close\"))\n```\n\nPlugin options:\n\n```lua\nhl.config({\n    plugin = {\n        hyprwinview = {\n            gap_size = 24,\n            margin = 48,\n            background = \"rgba(10101499)\",\n            background_blur = 0,\n            border_col = \"rgba(ffffff33)\",\n            hover_border_col = \"rgba(66ccffee)\",\n            border_size = 3,\n            window_order = \"natural\",\n            keys_default_action = \"return,enter,space,g,f\",\n            keys_filter_toggle = \"/\",\n            keys_filter_close = \"escape,ctrl+g\",\n            keys_filter_bring = \"ctrl+b\",\n            keys_filter_bring_replace = \"ctrl+shift+b\",\n            keys_filter_left = \"left,ctrl+a,super+a\",\n            keys_filter_right = \"right,ctrl+d,super+d\",\n            keys_filter_up = \"up,ctrl+p,ctrl+w,super+w\",\n            keys_filter_down = \"down,ctrl+n,ctrl+s,super+s\",\n            show_app_icon = 1,\n            app_icon_size = 48,\n            app_icon_theme = \"\",\n            app_icon_theme_source = \"auto\",\n            app_icon_overrides = \"\",\n            app_icon_position = \"bottom right\",\n            app_icon_anchor_x = -1.0,\n            app_icon_anchor_y = -1.0,\n            app_icon_margin_x = 10,\n            app_icon_margin_y = 10,\n            app_icon_margin_relative_x = 0.0,\n            app_icon_margin_relative_y = 0.0,\n            app_icon_offset_x = 0,\n            app_icon_offset_y = 0,\n            app_icon_backplate_col = \"rgba(00000066)\",\n            app_icon_backplate_padding = 6,\n            show_window_text = 1,\n            window_text_font = \"Sans\",\n            window_text_size = 14,\n            window_text_color = \"rgba(ffffffff)\",\n            window_text_backplate_col = \"rgba(00000099)\",\n            window_text_padding = 6,\n            filter_animation_ms = 140,\n            animation = \"workspace_zoom\",\n            animation_in_ms = 180,\n            animation_out_ms = 140,\n            animation_scale = 0.94,\n            animation_stagger_ms = 16,\n            animation_stagger_max_ms = 120,\n            animation_workspace_zoom_stage_ratio = 0.45,\n            animation_workspace_zoom_gap = 18,\n        },\n    },\n})\n\nhl.plugin.hyprwinview.configure({\n    keys = {\n        left = { \"a\", \"h\", \"left\" },\n        right = { \"d\", \"l\", \"right\" },\n        up = { \"w\", \"k\", \"up\" },\n        down = { \"s\", \"j\", \"down\" },\n        default_action = { \"return\", \"enter\", \"space\", \"g\", \"f\" },\n        bring = { \"b\", \"shift+return\", \"shift+space\" },\n        bring_replace = { \"shift + b\" },\n        close = { \"escape\", \"q\" },\n        filter_toggle = { \"/\" },\n        filter_close = { \"escape\", \"ctrl+g\" },\n        filter_bring = { \"ctrl+b\" },\n        filter_bring_replace = { \"ctrl+shift+b\" },\n        filter_left = { \"left\" },\n        filter_right = { \"right\" },\n        filter_up = { \"up\", \"ctrl+p\" },\n        filter_down = { \"down\", \"ctrl+n\" },\n    },\n})\n```\n\nKeyboard key sets are Lua arrays when configuring through\n`hl.plugin.hyprwinview.configure`. Modifiers can be written with `+`, for\nexample `shift+return` or `shift + b`. Modifier matching is exact for Shift,\nCtrl, Alt, and Super, so `b` and `shift + b` can trigger different actions. The\nscalar `keys_*` plugin options still work as a fallback for hyprlang-style\nconfiguration. `go` and `keys_go` are still accepted as legacy aliases for the\ndefault-action key set.\n\n`keys_filter_toggle` enters and leaves filter input mode while the overview is\nopen. In filter mode, printable keys update the filter query and only windows\nwhose title, class, initial title, or initial class contain all query tokens\nremain in the grid. The filter navigation key sets default to the arrow keys,\nwith `Ctrl+p` for up and `Ctrl+n` for down. `Backspace` and `Delete` delete one\ncharacter and repeat while held, `Ctrl+u` clears the query, `Escape` or\n`Ctrl+g` closes the overview, `Ctrl+b` brings the current match,\n`Ctrl+Shift+b` bring-replaces it, and Return selects it. Leaving filter mode\nkeeps the current narrowed set so normal navigation can continue over the\nmatches.\n\n`show_window_text` controls the per-window title/class labels. The text is drawn\nover each window snapshot with a configurable font, size, color, backplate, and\npadding. `filter_animation_ms` controls the short transition used when filter\nmatches narrow or expand the grid.\n\n`background` controls the full-screen overview tint. Use a low alpha like\n`rgba(10101466)` to leave the wallpaper visible, `rgba(10101400)` for no tint,\nor `rgba(101014ff)` for an opaque backdrop. Set `background_blur = 1` to blur\nthe wallpaper behind the overview. The older `bg_col` option still works as a\nlegacy alias when `background` is left at its default value.\n\n`window_order` accepts `natural` or `none` for the default Hyprland window order,\nor `application` to keep windows from the same application grouped together\nwhile preserving the first-seen group order and the within-application window\norder. Aliases like `compositor`, `app`, `group_by_app`, and `grouped_by_app`\nare also accepted.\n\n`app_icon_position` accepts `left`, `right`, `top`, `bottom`, and `center`,\nincluding combinations like `top left` or `bottom right`; single edges like\n`top` or `right` center the other axis. Set `app_icon_anchor_x` or\n`app_icon_anchor_y` to a value from `0.0` to `1.0` to override the token position\non an axis (`0.0` is left/top, `0.5` is center, `1.0` is right/bottom). Margins\nare logical pixels plus optional relative tile fractions; offsets are final\nlogical-pixel nudges.\n\nApp icons are resolved through freedesktop icon themes before falling back to a\nplain filesystem search. `app_icon_theme_source` accepts `auto`, `gtk`, `qt`,\n`none`, or `legacy`; `auto` reads GTK settings and Qt/KDE settings, preferring\nQt first on KDE/LXQt sessions. Set `app_icon_theme` to force a specific icon\ntheme name, for example `Papirus-Dark`. Set `app_icon_overrides` to a\ncomma-separated list of `app_id=icon` pairs, where `icon` can be a themed icon\nname or an absolute path.\n\n`animation` accepts `fade_scale`, `staggered`, `workspace_zoom`, `fade`, or `none`.\n`animation_scale` is the starting tile scale for scale-based modes; it is\nclamped between `0.01` and `1.0`. `animation_stagger_ms` and\n`animation_stagger_max_ms` control the per-tile delay for `staggered`.\n`workspace_zoom` treats windows as living in a fixed workspace grid. Workspace\n1 is placed in the first cell, workspace 2 in the second cell, and so on; nine\nnormal workspaces therefore produce a 3x3 plane. Other workspace counts use a\nnear-square grid sized from the highest normal workspace id Hyprland currently\nknows about. The animation starts with the camera zoomed into the initially\nfocused workspace's fixed cell, zooms out to reveal the workspace plane, then\nmoves and resizes windows into the final overview grid.\n`animation_workspace_zoom_stage_ratio` controls how much of the duration is\nspent reaching the workspace-plane view before moving to the final grid, and\n`animation_workspace_zoom_gap` controls the spacing between workspace cells in\nthat intermediate plane.\n\nOn Hyprland 0.54 and older hyprlang configs, the same options live under\n`plugin { hyprwinview { ... } }`.\n\n## Dispatchers\n\n```hyprlang\nhyprwinview:overview toggle\nhyprwinview:overview toggle other-workspaces\nhyprwinview:overview toggle filter\nhyprwinview:overview toggle default-action=bring\nhyprwinview:overview toggle-filter\nhyprwinview:overview toggle exclude-current-workspace\nhyprwinview:overview select\nhyprwinview:overview bring\nhyprwinview:overview bring-replace\nhyprwinview:overview close\n```\n\n`toggle` with no filter keeps the default behavior and includes windows from all\nworkspaces. Add `other-workspaces`, `exclude-current-workspace`,\n`without-current-workspace`, or `no-current-workspace` to omit windows on the\ncurrently active workspace when opening the overview. `open`, `show`, and `on`\nare also accepted when you want to open or replace the overview instead of\ntoggling it closed.\n\nAdd `filter`, `search`, `start-filter`, or `start-in-filter-mode` when opening\nthe overview to begin in filter input mode instead of normal navigation mode.\nUse `toggle-filter`, `filter-toggle`, `toggle-search`, or `search-toggle` to\ntoggle filter input mode on the active overview, or to open directly into filter\ninput mode if the overview is not already open.\n\nAdd `default-action=select`, `default-action=bring`, or\n`default-action=bring-replace` when opening the overview to choose what the\ndefault-action key set and tile clicks do for that overview invocation. The\ndefault is `select`.\n\nThe Lua function accepts the same string arguments, or a table:\n\n```lua\nhl.plugin.hyprwinview.overview({\n    action = \"toggle\",\n    include_current_workspace = false,\n    filter_mode = true,\n    default_action = \"bring\",\n})\n```\n\n`select` focuses the selected window. If the selected window is minimized on a\n`minimized` or `special:minimized` workspace, `select` restores it to the current\nworkspace like `bring` before focusing it. `bring-replace` swaps the selected\nwindow with the window that was focused when the overview opened, then focuses\nthe selected window. If that original focused window no longer exists, it falls\nback to normal bring behavior.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcolonelpanic8%2Fhyprwinview","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcolonelpanic8%2Fhyprwinview","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcolonelpanic8%2Fhyprwinview/lists"}