{"id":19349107,"url":"https://github.com/Neurarian/matshell","last_synced_at":"2025-04-23T06:30:50.701Z","repository":{"id":242291822,"uuid":"809153262","full_name":"Neurarian/matshell","owner":"Neurarian","description":"Astal / AGS desktop \u0026 laptop shell config for Hyprland.","archived":false,"fork":false,"pushed_at":"2025-04-13T01:17:55.000Z","size":698,"stargazers_count":11,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-13T01:28:48.278Z","etag":null,"topics":["ags","astal","dotfiles","gtk4","hyprland","linux","linux-rice","material-design","nix"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Neurarian.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}},"created_at":"2024-06-01T21:09:31.000Z","updated_at":"2025-04-13T01:17:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"d1826e92-1fc4-4a20-8469-4d39df55fdab","html_url":"https://github.com/Neurarian/matshell","commit_stats":null,"previous_names":["neurarian/ags-bar","neurarian/matshell"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Neurarian%2Fmatshell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Neurarian%2Fmatshell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Neurarian%2Fmatshell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Neurarian%2Fmatshell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Neurarian","download_url":"https://codeload.github.com/Neurarian/matshell/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250384720,"owners_count":21421783,"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":["ags","astal","dotfiles","gtk4","hyprland","linux","linux-rice","material-design","nix"],"created_at":"2024-11-10T04:24:45.935Z","updated_at":"2025-04-23T06:30:50.691Z","avatar_url":"https://github.com/Neurarian.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Matshell\n\n### A GTK4 Material Design desktop shell powered by [Astal](https://github.com/Aylur/astal)\n\n![GitHub repo size](https://img.shields.io/github/repo-size/neurarian/matshell?style=for-the-badge\u0026logo=gitlfs\u0026logoColor=%23FFDBC9\u0026labelColor=%2346362d\u0026color=%23FFDBC9)\n![GitHub commit activity](https://img.shields.io/github/commit-activity/m/neurarian/matshell?style=for-the-badge\u0026logo=git\u0026logoColor=%23FFB68D\u0026labelColor=%2346362d\u0026color=%23FFB68D)\n![GitHub last commit (branch)](https://img.shields.io/github/last-commit/neurarian/matshell/master?style=for-the-badge\u0026logo=git\u0026logoColor=%23EDBD92\u0026labelColor=%2346362d\u0026color=%23EDBD92)\n![GitHub Repo stars](https://img.shields.io/github/stars/neurarian/matshell?style=for-the-badge\u0026logo=github\u0026logoColor=%23ECBF78\u0026labelColor=%2346362d\u0026color=%23ECBF78)\n\n![Neurarian_Matshell_round-2](https://github.com/user-attachments/assets/f3a2cbf8-6f62-4047-938f-68a4a01d8cd3)\n\n\u003c/div\u003e\n\nMatshell is a Material Design inspired desktop shell built with [Astal](https://github.com/Aylur/astal) for [Hyprland](https://github.com/hyprwm/Hyprland). This project draws heavy inspiration from [fufexan's](https://github.com/fufexan/dotfiles) AGSv1 config, with design influences from [saimoomedits](https://github.com/saimoomedits/eww-widgets), tailored for both multi-monitor desktop setups and laptops.\n\nThis setup tries to achieve sleek, \"MacOS-esque\" looks with a little bit of rice sprinkled on top.\n\n***Now shipped with some configurable options*** via autogenerated config.json.\n\n## Features\n\n- **Adaptive Layout**: Automatically adapts to desktop or laptop environments by conditionally rendering notebook-specific widgets\n- **Dynamic Material Design Theming**: Change themes on-the-fly using either scripts I botched from [end-4](https://github.com/end-4/dots-hyprland) or via [matugen](https://github.com/InioX/matugen) templates\n- **Multi-monitor Support**: Designed with multi-monitor setups in mind\n- **Hyprland Integration**: Built specifically for the Hyprland compositor\n- **Nix Support**: Support for NixOS / Home-Manager with dedicated module\n\n\u003cdetails\u003e\n  \u003csummary\u003eWidget List\u003c/summary\u003e\n\n- **Main Status Bar**\n\n![2025-04-10 18-58-06](https://github.com/user-attachments/assets/1952d0ed-c9ca-4966-a91f-5f45aae5fdf6)\n\n![2025-04-10 23-47-32](https://github.com/user-attachments/assets/e05e8861-2e76-417a-a7b3-369f155b20c1)\n\n- Laptop (Light)\n\n![2025-03-23T18:37:29,615714672+01:00](https://github.com/user-attachments/assets/8656aa43-7793-476b-9e12-f0a58eeccbfb)\n\n- Desktop (Dark)\n\n![2025-03-23T18:53:49,228938439+01:00](https://github.com/user-attachments/assets/01e4e84c-1901-4532-a924-3a86696aa22c)\n\n- **App Launcher**\n- Light\n\n![2025-03-23T18:41:51,470421774+01:00](https://github.com/user-attachments/assets/ae8b69a8-8fc1-4a48-a18e-77a8af6f83c8)\n\n- Dark\n\n![2025-03-23T18:56:24,165287965+01:00](https://github.com/user-attachments/assets/3760a241-913f-4d31-a90b-f1a6d85b59bf)\n\n- **Logout Menu**\n- Light\n\n![2025-03-23T19:00:49,303694058+01:00](https://github.com/user-attachments/assets/df572fad-1783-45fe-b7ca-a43fd3d55319)\n\n- Dark\n\n![2025-03-23T18:40:10,844462569+01:00](https://github.com/user-attachments/assets/53eb4206-b33d-459c-b3b4-d6cb1154c4f3)\n\n- **Music Player with CAVA**\n\n![2025-04-10T00:02:06,878048376+02:00](https://github.com/user-attachments/assets/cefb1942-4f9b-430e-b499-55ebf32e55e5) ![2025-04-10 18-22-52-8](https://github.com/user-attachments/assets/512b6658-d7e5-44aa-95cc-7a180cf28203)\n\n- **Notifications**\n- Light\n\n![2025-03-23T18:42:09,143344616+01:00](https://github.com/user-attachments/assets/cacd60a8-4941-40d4-802c-54a683ff8b34)\n\n- Dark\n\n![2025-03-23T19:05:38,240008405+01:00](https://github.com/user-attachments/assets/c949ade2-2d3b-4678-a36e-0ff725859e05)\n\n- **On Screen Display**\n- Light\n\n![2025-03-23T18:47:25,513704415+01:00](https://github.com/user-attachments/assets/86351939-d32a-4063-bd6f-c4f2b9e7292d)\n\n- Dark\n\n![2025-03-23T19:06:59,375609741+01:00](https://github.com/user-attachments/assets/3ea5eb01-1042-4740-ad88-ee59212dc50c)\n\n- **System Menu**\n- Laptop (Light)\n\n![2025-03-23T18:38:30,002859605+01:00](https://github.com/user-attachments/assets/c520f03b-f365-4782-8008-591a8993eaef)\n\n- Desktop (Dark)\n\n![2025-03-23T19:09:22,826684018+01:00](https://github.com/user-attachments/assets/8c701cb4-d675-4bf9-97fa-cf3eceaa9545)\n\n\u003c/details\u003e\n\n______________________________________________________________________\n\n### ⛓️ Dependencies\n\n\u003cdetails\u003e\n  \u003csummary\u003eShow dependency list\u003c/summary\u003e\n\n#### Required:\n\n- astal\n- ags\n- glibtop\n- hyprland\n- adw-gtk3-git\n- adwaita-icon-theme\n- coreutils\n- dart-sass\n- imagemagick\n- Material Symbols Outlined Font\n- Fira Code Nerd Font\n- ***For the end-4 scripts:***\n  - python-materialyoucolor-git\n  - gradience-git\n  - python-libsass\n  - python-material-color-utilities\n  - python-build\n  - python-pillow\n  - python-pywal\n  - python-setuptools-scm\n  - python-wheel\n- ***For matugen:***\n  - matugen\n  - [image-hct](https://github.com/Neurarian/image-hct) (optional; for additional chroma/tone based theming)\n\n#### Not required but launched by Astal widgets:\n\n- gnome-control-center\n- mission-center\n- overskride\n- pwvucontrol\n\n\u003c/details\u003e\n\n### 🛠️ Installation\n\nRun the installation script:\n\n```console\n bash \u003c(curl -s https://raw.githubusercontent.com/Neurarian/matshell/refs/heads/master/install.sh)\n```\n\n\u003cdetails\u003e\n  \u003csummary\u003eManual install\u003c/summary\u003e\n\n...Or do it manually by cloning this repo...\n\n**❗Make sure to create a backup of your current config if you want to keep it❗**\n\n```console\n  git clone --depth 1 \"https://github.com/Neurarian/matshell\" \"$XDG_CONFIG_HOME/ags/\"\n```\n\nFor the color generation with the end-4-scripts to work, run this command to create the necessary additional directories:\n\n```console\nmkdir -p $XDG_STATE_HOME/astal/{scss,user} $XDG_CACHE_HOME/astal/user/generated\n```\n\n\u003c/details\u003e\n\nAfter using hyprpaper or some other means to set your wallpaper, run the script from [end-4](https://github.com/end-4/dots-hyprland) like this:\n\n```console\n$HOME/.config/astal/scripts/colorgen.sh \"$HOME/.cache/current_wallpaper.jpg\" --apply --smart\n```\n\nThe color generation works better with wallpapers that have a bit of chroma.\n\n#### ❄️ Nix\n\nFor a NixOS implementation and example [script](https://github.com/Neurarian/matshell/blob/master/nix/hm-module.nix) for use with hyprpaper, matugen, and a [custom cli utility](https://github.com/Neurarian/image-hct) to get chroma/tone, you can enable dedicated options in the home-manager module exposed by the flake (see below).\n\nYou can generally test out matshell via the flake exposed package `nix run github:Neurarian/matshell` , but I would recommend to also imperatively copy or symlink this repo to your dotfiles to circumvent nix-store immutability. Otherwise the dynamic theming will not work. One way to do this would be via the home-manager module which overwrites the ags options with the following:\n\n```nix\n# ...\n\nimports = [\n  inputs.matshell.homeManagerModules.default\n];\n\nprograms.ags = {\n  matshell = { \n    # Enable the basic shell\n    enable = true; \n    # Enable a systemd service for matshell\n    service = true;\n    # Enable matugen theming via custom random wallpaper setter script and rust utility\n    # used to base theme and scheme on the HCT properties of the main color.\n    # Run this via \"wal_set\"\n    matugenThemeSetter = true;\n    # This also sets up the entire matugen config \u0026 templates.\n    # If you already have matugen set up you may want to omit this.\n    # To use the hyprland/hyprlock templates, you would still need to\n    # import the generated files and add the color aliases to your config as desired.\n    matugenConfig = true;\n  };\n};\n#...\n\n```\n\nThis will simply clone the repo for you to .config/ags if that dir does not exist, build ags wrapped with all dependencies for matshell, and start a systemd service. You will have to \u003cins\u003eremove the ags home-manager module\u003c/ins\u003e from your config, as enabling matshell will handle everything ags-related for you.\n\nThis is absolutely hacky, probably unsafe, and not the nix way to do it, but it gets the job done for now. To get the latest version of matshell, you would have to pull the updates manually or delete .config/ags and rebuild the system/home-manager profile.\n\n## Acknowledgements\n\nThis project wouldn't be possible without:\n\n- [fufexan's dotfiles](https://github.com/fufexan/dotfiles) for the initial inspiration and foundation\n- [end-4's dots-hyprland](https://github.com/end-4/dots-hyprland) for the color generation scripts\n- [matugen](https://github.com/InioX/matugen) for the amazing Material Color theming utility\n- [saimoomedits' eww-widgets](https://github.com/saimoomedits/eww-widgets) for design influence\n- [kotontrion](https://github.com/kotontrion/kompass) for the GTK4 CAVA Catmull-Rom spline widget\n- [ARKye03](https://github.com/ARKye03) for the GTK4 circular progress widget which is currently still on its way to be merged into Astal\n- [Astal](https://github.com/Aylur/astal) for the powerful widget toolkit\n\n______________________________________________________________________\n\n## Screenshots\n\n### 🌚 Dark Theme (Desktop)\n\n\u003cp align=\"center\"\u003e\n\u003cb\u003eFloating Mode\u003c/b\u003e\n  \n![2025-04-19T03:27:33,093645867+02:00](https://github.com/user-attachments/assets/603b7837-ebac-4ff8-90b8-32721ea5aeae)\n\n\u003cp align=\"center\"\u003e\n\u003cb\u003eFull Bar Mode \u0026 Cava in Bar\u003c/b\u003e\n  \n![2025-04-19T03:22:32,664157108+02:00](https://github.com/user-attachments/assets/458f11ac-2de2-455c-847b-15bd515a8f48)\n\u003c/p\u003e\n\n### 🌞 Light Theme (Desktop)\n\n\u003cp align=\"center\"\u003e\n\n![2025-03-21T22:37:54,320570898+01:00](https://github.com/user-attachments/assets/45bf6c1a-d931-40a1-8644-fd7ccbfb4f95)\n![2025-03-21T22:52:59,913307252+01:00](https://github.com/user-attachments/assets/444a6624-9c36-412a-b265-2a887717c933)\n\n\u003c/p\u003e\n\n### Video Demo (quite outdated)\n\n\u003cp align=\"center\"\u003e\n  \u003cvideo src=\"https://github.com/Neurarian/ags-bar/assets/110474238/3f01073e-552a-479b-99f9-d82647138e55\" controls width=\"600\"\u003e\u003c/video\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNeurarian%2Fmatshell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNeurarian%2Fmatshell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNeurarian%2Fmatshell/lists"}