{"id":20963786,"url":"https://github.com/mitjafelicijan/clutch","last_synced_at":"2026-04-21T23:03:00.590Z","repository":{"id":245015955,"uuid":"816082864","full_name":"mitjafelicijan/clutch","owner":"mitjafelicijan","description":"Clutch allows you to run nested dwm session inside your existing X or Wayland session. This comes in handy when you already have a desktop environment running (like Gnome) but you want to have a tiling window manager as well.","archived":false,"fork":false,"pushed_at":"2025-04-08T18:48:20.000Z","size":40,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-12-31T16:05:56.768Z","etag":null,"topics":["dmenu","dwm","st","wayland","winc","x11"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mitjafelicijan.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-06-17T02:10:32.000Z","updated_at":"2025-04-09T09:48:05.000Z","dependencies_parsed_at":"2024-06-19T03:07:40.684Z","dependency_job_id":null,"html_url":"https://github.com/mitjafelicijan/clutch","commit_stats":null,"previous_names":["mitjafelicijan/clutch"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mitjafelicijan/clutch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitjafelicijan%2Fclutch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitjafelicijan%2Fclutch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitjafelicijan%2Fclutch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitjafelicijan%2Fclutch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mitjafelicijan","download_url":"https://codeload.github.com/mitjafelicijan/clutch/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitjafelicijan%2Fclutch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32113748,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-21T11:25:29.218Z","status":"ssl_error","status_checked_at":"2026-04-21T11:25:28.499Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["dmenu","dwm","st","wayland","winc","x11"],"created_at":"2024-11-19T02:48:25.621Z","updated_at":"2026-04-21T23:03:00.562Z","avatar_url":"https://github.com/mitjafelicijan.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Preview](https://github.com/mitjafelicijan/clutch/assets/296714/dca4a47a-d33e-46fd-8a45-b54b633909a2)\n\n# Nested X11 dwm sessions\n\nClutch allows you to run nested `dwm` session inside your existing X or Wayland\nsession. This comes in handy when you already have a desktop environment\nrunning (like Gnome) but you want to have a tiling window manager as well.\n\n\u003e [!NOTE]\n\u003e Even though this was tested and works on X11 and on Wayland I use it on X11\n\u003e exclusively. So, your millage may vary.\n\nAll this can be achieved manually, this script just packages all the commands\ninto a nice package that is easy to use. Please check `clutch.sh` script to see\nhow it was done. Nothing magical happening here.\n\n# Why?\n\nPersonally I like having Gnome as my main window manager because it comes with\nall the niceties and quality of life stuff like network management, calendar\nintegration etc. You could achieve this in tiling window managers but it would\ntake more work. As far as it goes for coding and the work I do regularly I do\nprefer tiling window managers.\n\nThere are some extensions available for Gnome that introduce tiling but none of\nthem were up to par with proper tiling window manager like `dwm` or `i3`.\n\n# How?\n\nI had to choose a stack to make this project viable and not be this impossible\nall in one solution. So I choose something that is easily reproducible on every\nmachine.\n\nBecause of this reason, this project heavily relies on several\n[Suckless](https://suckless.org/) programs such as:\n\n- dwm - https://dwm.suckless.org/\n- dmenu - https://tools.suckless.org/dmenu/\n- st - https://st.suckless.org/\n\nThese three programs together gives us tiling window manager, lean terminal\nemulator and dynamic menu (program launcher).\n\nThe secret ingredient in all this is\n[Xephyr](https://en.wikipedia.org/wiki/Xephyr) which allows us to run nested X\nserver.\n\n\u003e [!IMPORTANT]\n\u003e Because some of the applications are downloaded and need to be compiled GCC\n\u003e or Clang and some other software is required. More on this is described later\n\u003e in the readme file.\n\nThis approach **DOES NOT** require `dwm`, `dmenu` or `st` to be installed on\nyour machine. All these dependencies will be downloaded and compiled\nautomatically.  When `$PATH` gets updated by the `clutch.sh` script all\ndownloaded versions will be preferred to system ones.\n\nTested on:\n\n- Debian 12 Bookworm with GNOME Shell 43.9 on X11\n- Ubuntu 24.04 Noble Numbat with GNOME Shell 46.0 on Wayland\n- Fedora Workstation 40 with GNOME Shell 46.0 on Wayland\n- Manjaro 24.0.2 with GNOME Shell 46.2 on X11\n\n## Installation \u0026 Usage\n\nSome prerequisites are required for the compilation of `dwm`, `dmenu` and `st`. \n\n```sh\n# Debian 12 or Ubuntu 24.04\nsudo apt install git gcc make libx11-dev libxinerama-dev libxft-dev xserver-xephyr x11-xserver-utils\n\n# Fedora Workstation 40\nsudo dnf install git gcc make xorg-x11-server-Xephyr libX11-devel libXinerama-devel libXft-devel xrandr\n\n# Manjaro 24.0.2\nsudo pacman -Su git gcc make base-devel extra/xorg-server-xephyr extra/libx11 extra/libxinerama extra/libxft extra/xorg-xrandr\n```\n\nAfter the installation of prerequisites we can continue with downloading and\nbootstrapping of necessary dependencies.\n\n```sh\ngit clone https://github.com/mitjafelicijan/clutch\ncd clutch\n\n# This will download dwm, dmenu, st and compile them all.\nbash clutch.sh --bootstrap\n\n# After that we can run our first nested desktop with.\nbash clutch.sh --run\n```\n\nYou can have multiple nested desktop environments and they will each get unique\nX11 server display id.\n\n\u003e [!IMPORTANT]\n\u003e Since all the software will be downloaded to `$XDG_CACHE_HOME/clutch` you can\n\u003e put `clutch.sh` in your `$PATH` to make it easily available from everywhere.\n\u003e All code regarding this project lived in `clutch.sh` file so there is no fear\n\u003e of missing something when moving this tool around.\n\n`clutch.sh` has several options available via arguments.\n\n```sh\n$ bash clutch.sh --help\nUsage: clutch.sh [--bootstrap | --run | --kilall | --info]\n  --bootstrap    Downloads and compiles required software\n  --run          Runs dwm session in Xephyr\n  --killall      Kills all running Xephyr and dwm instances\n  --info         Displays all relavant paths and settings for Clutch\n```\n\n- Bootstrap should be used only for the first time to prepare environment.\n- Most of the time you will be using `--run` which starts a session.\n- `--killall` is a nuclear option if something goes wrong and some sessions are\n  still running even though you closed them.\n- Info with `--info` is there just to tell you which software versions are you\n  running and which paths apply to your setup.\n\n\u003e [!TIP]\n\u003e If you resize the window manually execute `xrandr` program in your `Xephyr`\n\u003e session to make `dwm` the size of the window.\n\n## Configuration\n\nAll the configuration is done in the `clutch.sh` file itself.\n\n```sh\n# General settings for the Xephyr session.\nDISPLAY_ID=50         # Start X server display id.\nRESOLUTION=1280x720   # Initial resolution, can be resized later.\nDPI=96                # DPI settings. On high DPI display adjust this value.\nXEPHYR_FLAGS=\"-ac -br -noreset -no-host-grab\" # Additional flags.\n\n# Used when downloading the source tarballs.\nDWM_VERSION=6.5    # dwm version used.\nDMENU_VERSION=5.3  # dmenu version used.\nST_VERSION=0.9.2   # st terminal version used.\n```\n\nAdditional configuration can be done after the bootstraping is done. Execute\n`bash clutch.sh --info` to see all the paths used.\n\n- dwm - `$CLUTCH_PATH/dwm-{version}/config.def.h`\n- dmenu - `$CLUTCH_PATH/dmenu-{version}/config.def.h`\n- st - `$CLUTCH_PATH/st-{version}/config.def.h`\n\n`$CLUTCH_PATH` respects `$XDG_CACHE_HOME` variable and if nothing is set by\nuser defaults to `~/.config/clutch`.\n \n## Acknowledgment\n\n- https://stackoverflow.com/a/31443098\n\n## Alternatives\n\n- https://github.com/paperwm/PaperWM\n- https://github.com/material-shell/material-shell\n- https://github.com/pop-os/shell\n- https://github.com/gTile/gTile\n- https://github.com/regolith-linux\n\n## License\n\n[clutch](https://github.com/mitjafelicijan/clutch) was written by [Mitja\nFelicijan](https://mitjafelicijan.com) and is released under the BSD\ntwo-clause license, see the LICENSE file for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmitjafelicijan%2Fclutch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmitjafelicijan%2Fclutch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmitjafelicijan%2Fclutch/lists"}