{"id":13533571,"url":"https://github.com/thrombe/hyprkool","last_synced_at":"2025-04-01T21:32:29.241Z","repository":{"id":228089793,"uuid":"773132456","full_name":"thrombe/hyprkool","owner":"thrombe","description":"Hyprland  plugin to replicate the feel of kde activities and desktop grid layout","archived":false,"fork":false,"pushed_at":"2025-02-01T19:30:49.000Z","size":591,"stargazers_count":63,"open_issues_count":6,"forks_count":6,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-01T23:34:39.159Z","etag":null,"topics":["harpoon","hyprland","hyprland-plugin"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thrombe.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}},"created_at":"2024-03-16T20:50:43.000Z","updated_at":"2025-02-01T19:27:04.000Z","dependencies_parsed_at":"2024-05-18T19:29:09.584Z","dependency_job_id":"632c6ef3-8f30-4c4a-bb70-0fb696c14b34","html_url":"https://github.com/thrombe/hyprkool","commit_stats":null,"previous_names":["thrombe/hyprkool"],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thrombe%2Fhyprkool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thrombe%2Fhyprkool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thrombe%2Fhyprkool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thrombe%2Fhyprkool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thrombe","download_url":"https://codeload.github.com/thrombe/hyprkool/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246713458,"owners_count":20821893,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["harpoon","hyprland","hyprland-plugin"],"created_at":"2024-08-01T07:01:21.092Z","updated_at":"2025-04-01T21:32:29.228Z","avatar_url":"https://github.com/thrombe.png","language":"Rust","funding_links":[],"categories":["Tools"],"sub_categories":["Workspace"],"readme":"# Hyprkool\nAn opinionated [Hyprland](https://github.com/hyprwm/Hyprland) plugin that tries to replicate the feel of KDE activities and grid layouts.\n\n### Demo Video\nCheck out our [demo video](https://youtu.be/tim5r6Yo6TA) to see Hyprkool in action:\n\n[![overview](./screenshots/overview.jpg)](https://www.youtube.com/watch?v=tim5r6Yo6TA)\n\n# Features\n- switch desktops when cursor touches screen edges\n- grid layout\n- info commands for tools like eww and waybar\n- an optional daemon for stateful commands\n- a grid overview\n- [harpoon](https://github.com/ThePrimeagen/harpoon) but for hyprland workspaces\n\n# Usage\nHyprkool consists of two main components: a CLI + daemon written in Rust and a C++ plugin.\nThe CLI and daemon collectively provide most of the functionality.\nAdditionally, there's an optional C++ plugin that offers a couple of features.\n- Changing workspace animations based on movement direction.\n- Grid overview.\n\nThe daemon component of Hyprkool is also optional but required for certain features, including:\n- Desktop switching when the cursor touches screen edges.\n- Remembering the last workspace per activity.\n- Harpoon for workspaces (named-focus)\n\n# Version Compatibility\nThe plugin is tested and compatible with the following versions of Hyprland. While the daemon and cli should work with any reasonably new version of Hyprland.\n\n| Hyprland version      | hyprkool version      |\n| ------------- | ------------- |\n| [v0.39.x](https://github.com/hyprwm/Hyprland/releases/tag/v0.39.1) | [v0.5.x](https://github.com/thrombe/hyprkool/releases/tag/0.5.3) |\n| [v0.40.x](https://github.com/hyprwm/Hyprland/releases/tag/v0.40.0) | [v0.6.x](https://github.com/thrombe/hyprkool/releases/tag/0.6.0) |\n| [v0.41.0](https://github.com/hyprwm/Hyprland/releases/tag/v0.41.0), [v0.41.1](https://github.com/hyprwm/Hyprland/releases/tag/v0.41.1) | [v0.7.0](https://github.com/thrombe/hyprkool/releases/tag/0.7.0) |\n| [v0.41.2](https://github.com/hyprwm/Hyprland/releases/tag/v0.41.2) | [v0.7.1](https://github.com/thrombe/hyprkool/releases/tag/0.7.1) |\n| [v0.42.0](https://github.com/hyprwm/Hyprland/releases/tag/v0.42.0), [v0.43.0](https://github.com/hyprwm/Hyprland/releases/tag/v0.43.0), [v0.44.x](https://github.com/hyprwm/Hyprland/releases/tag/v0.44.1) | [v0.7.2](https://github.com/thrombe/hyprkool/releases/tag/0.7.2) |\n| [v0.45.x](https://github.com/hyprwm/Hyprland/releases/tag/v0.45.2) | [v0.7.3](https://github.com/thrombe/hyprkool/releases/tag/0.7.3) |\n| [v0.46.x](https://github.com/hyprwm/Hyprland/releases/tag/v0.46.2) | [v0.7.4](https://github.com/thrombe/hyprkool/releases/tag/0.7.4) |\n| [v0.47.x](https://github.com/hyprwm/Hyprland/releases/tag/v0.47.1) | [v0.7.5](https://github.com/thrombe/hyprkool/releases/tag/0.7.5) |\n\n# Installing Cli/Daemon\n\u003c!-- enable when new version of hyprland-rs drops --\u003e\n\u003c!-- ### Cargo --\u003e\n\u003c!-- ```zsh --\u003e\n\u003c!-- cargo install --locked hyprkool --\u003e\n\u003c!-- ``` --\u003e\n\n## Install from source\n```zsh\ngit clone https://github.com/thrombe/hyprkool\ncd hyprkool\ncargo install --locked --path .\n```\n\n## Nix\nTry it out\n```nix\nnix run github:thrombe/hyprkool\n```\n\nElse add the following to your nix flake\n```nix\n{\n  inputs = {\n    # ...\n    # define flake input\n    hyprkool.url = \"github:thrombe/hyprkool\";\n  };\n\n  # ...\n\n    # then add it to your environment packages\n    packages = [\n      inputs.hyprkool.packages.\"${system}\".default\n    ];\n\n  # ...\n}\n```\n\n## Installing the Plugin\n### using [hyprpm](https://wiki.hyprland.org/0.39.0/Plugins/Using-Plugins/#hyprpm)\n```zsh\nhyprpm add https://github.com/thrombe/hyprkool\nhyprpm enable hyprkool\n```\n\n### Nix\nIt is recommended that you are using Hyprland flake.\nYou can install hyprkool plugin just like other [hyprland plugins](https://github.com/hyprwm/hyprland-plugins?tab=readme-ov-file#nix).\n\n#### with hyprland as a flake\n```nix\n{\n  inputs = {\n    # ...\n    hyprland.url = \"github:hyprwm/Hyprland\";\n    hyprkool = {\n      url = \"github:thrombe/hyprkool\";\n      inputs.hyprland.follows = \"hyprland\";\n    };\n  };\n\n  # ...\n\n    # then, you can use the plugins with the Home Manager module\n    {inputs, pkgs, ...}: {\n      wayland.windowManager.hyprland = {\n        enable = true;\n        # ...\n        plugins = [\n          inputs.hyprkool.packages.${pkgs.system}.hyprkool-plugin\n          # ...\n        ];\n      };\n    }\n\n  # ...\n}\n```\n\n#### with hyprland from nixpkgs\n```nix\n{\n  inputs = {\n    # ...\n    hyprkool.url = \"github:thrombe/hyprkool\";\n  };\n\n  # ...\n\n    # then, you can use the plugins with the Home Manager module\n    {inputs, pkgs, ...}: {\n      wayland.windowManager.hyprland = {\n        enable = true;\n        # ...\n        plugins = [\n          inputs.hyprkool.packages.${pkgs.system}.hyprkool-plugin.override {\n            hyprland = pkgs.hyprland;\n          }\n          # ...\n        ];\n      };\n    }\n\n  # ...\n}\n```\n\n# Example Configs\n## Configure hyprkool\n~/.config/hypr/hyprkool.toml\n```toml\n# activity names (first activity is treated as default)\n# note: only a-z A-Z 0-9 - _ characters are allowed in the name\nactivities = [\"my-default-activity\", \"my-activity\"]\n\n# number of workspaces in x and y dimensions\nworkspaces = [2, 2]\n\n[daemon]\n# remember last focused workspace in an activity\nremember_activity_focus = true\n\n# execute fallback commands if daemon cannot be reached\nfallback_commands = true\n\n[daemon.mouse]\nswitch_workspace_on_edge = true\n\n# how often to poll for cursor position\npolling_rate = 300 # in ms\n\n# number of pixels to consider as edge\nedge_width = 0\n\n# number of pixels to push cursor inside when it loops around\nedge_margin = 2\n```\n\n## Hyprland config\n~/.config/hypr/hyprland.conf\n```conf\nanimations {\n  ...\n\n  # i recommend setting workspace animations to fade by default\n  # hyprkool plugin will set the animation to slide with appropriate\n  # direction when you switch between workspaces\n  animation = workspaces, 1, 2, default, fade\n}\n\n# default hyprkool plugin configuration\nplugin {\n    hyprkool {\n        overview {\n            hover_border_color = rgba(33ccffee)\n            focus_border_color = rgba(00ff99ee)\n            workspace_gap_size = 10\n        }\n    }\n}\n\n# Switch activity\nbind = $mainMod, TAB, exec, hyprkool next-activity -c\n\n# Move active window to a different acitvity\nbind = $mainMod CTRL, TAB, exec, hyprkool next-activity -c -w\n\n# Relative workspace jumps\nbind = $mainMod, h, exec, hyprkool move-left -c\nbind = $mainMod, l, exec, hyprkool move-right -c\nbind = $mainMod, j, exec, hyprkool move-down -c\nbind = $mainMod, k, exec, hyprkool move-up -c\n\n# Move active window to a workspace\nbind = $mainMod CTRL, h, exec, hyprkool move-left -c -w\nbind = $mainMod CTRL, l, exec, hyprkool move-right -c -w\nbind = $mainMod CTRL, j, exec, hyprkool move-down -c -w\nbind = $mainMod CTRL, k, exec, hyprkool move-up -c -w\n\n# toggle special workspace\nbind = $mainMod, SPACE, exec, hyprkool toggle-special-workspace -n minimized\n# move active window to special workspace without switching to that workspace\nbind = $mainMod, s, exec, hyprkool toggle-special-workspace -n minimized -w -s\n\n# harpoon for workspaces (previously known as named-focus :P)\n# switch to named focus\nbind = $mainMod, 1, exec, hyprkool switch-named-focus -n 1\nbind = $mainMod, 2, exec, hyprkool switch-named-focus -n 2\nbind = $mainMod, 3, exec, hyprkool switch-named-focus -n 3\n# set / delete named focus\nbind = $mainMod SHIFT, 1, exec, hyprkool set-named-focus -n 1\nbind = $mainMod SHIFT, 2, exec, hyprkool set-named-focus -n 2\nbind = $mainMod SHIFT, 3, exec, hyprkool set-named-focus -n 3\n\n# this only works if you have the hyprkool plugin\nbind = $mainMod, b, exec, hyprkool toggle-overview\n\n# this is optional, but it can provide features like\n# - remembering the last focused workspace in an activity\n# - switch workspaces when mouse touches screen edges\n# - named focus\nexec-once = hyprkool daemon -m\n\n# to load the plugin at startup: https://wiki.hyprland.org/0.39.0/Plugins/Using-Plugins/#hyprpm\nexec-once = hyprpm reload -n\n```\n\n## Troubleshooting\n#### hyprkool move-xxx does not work\nFor some of the hyprkool commands to work correctly, you need to switch to a hyprkool activity\n\n#### Hyprkool can't find icons?\nIf hyprkool can't find icons, you can specify the name of the icon pack for hyprkool to use. for example\n```zsh\n# assuming the Papirus icons are installed\nhyprkool info -m active-workspace-windows -t Papirus\n```\n\n#### Some command does not work\nIf a command does not work when using keybinds, try executing the same command in a terminal. Sometimes the error messages\nwill give you a clue into what could be wrong.\nAlso try using `--force-no-daemon` flag to check if something is wrong with the running daemon.\n\n#### Hyprkool does not do anything when run using Hyprland keybinds\ndepending on how you install hyprkool cli, hyprland's `exec` dispatch might have some trouble finding your hyprkool binary.\nin such cases, i recommend doing something like this:\nfirst run `which hyprkool` in your terminal and copy the path.\nthen make the following changes to hyprland.conf\n```conf\n$hyprkool = \"/absolute/path/to/hyprkool\"\n\n# then set up any keybinds using this variable\nbind = $mainMod, b, exec, $hyprkool toggle-overview\n```\n## Info commands\nHyprkool supports some additional info commands that help you to build widgets using applications like\n[waybar](https://github.com/Alexays/Waybar) and [eww](https://github.com/elkowar/eww).\n\nfor example, ```hyprkool info -m active-window``` prints the active window information.\n\nNote: the --monitor or -m flag makes this info print in an infinite loop. this however is very efficient\nas it is event based and not polling based.\neww (using [`deflisten`](https://github.com/elkowar/eww/blob/f1ec00a1c9a24c0738fb5d5ac309d6af16e67415/docs/src/configuration.md#adding-dynamic-content))\nand waybar (using [`exec`](https://github.com/Alexays/Waybar/wiki/Module:-Custom#continuous-script)) both support\nthis kind of efficient updates.\n\n### Eww config\nExample eww config can be found in [my dotfiles](https://github.com/thrombe/dotfiles-promax/blob/87593cb6ef9718475a3b57ce6a4a2a9727ba2eee/configma/tools/home/.config/eww/eww.yuck).\n\n# Contributing\nContributions are welcome to Hyprkool! If you're fixing a bug, adding a feature, or making an improvement, feel free to submit a pull request (PR) to help enhance the plugin.\n\n### Guidelines:\n- Target the `dev` branch for all contributions. This ensures the `master` branch remains stable while we continue to work on new features and fixes.\n- Provide clear reproduction steps when fixing a bug. If you're resolving an issue, include detailed instructions on how to reproduce the bug so the fix can be verified.\n- Test your changes. If you're introducing new functionality or addressing a bug, ensure everything works as expected.\n\nIf you have any questions or concerns about your contribution, don't hesitate to open an issue or ask for feedback.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthrombe%2Fhyprkool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthrombe%2Fhyprkool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthrombe%2Fhyprkool/lists"}