Brain_Shell

A dynamic, highly modular Wayland desktop shell built with Quickshell and QML, tailored for Hyprland.

Last Commit Stars Version 0.1.0
Hyprland v0.55+ Quickshell Framework
License Issues Discord Invite

---

Showcase

---

Features

- **Modular Setup** — Unintrusive setup - **Material You Integration** — Dynamic colors via Matugen - **Lua-Based Config** — Hyprland v0.55+ compatible - **System Dashboard** — Monitor CPU, RAM, battery, temps, and more - **Kanban/Tasks** — To Do, Ongoing and Competed lists with Prioiry and Deadlines - **App Launcher** — Dropdown App Launcher - **Keybinds** — Set your own keybinds for each popup - **Theming Engine** — Live wallpaper-synced color updates - **Network Manager** — WiFi, Bluetooth, VPN integration - **Notifications** — DBus Notifcations via libnotify - **Audio Control** — PipeWire volume & device management - **Screen Recorder** — Built-in recording with wf-recorder - **Clipboard Manager** — Cliphist integration for history management - **Highly Customizable** — QML-based UI, easily extended > **Note:** Brain Shell is currently in its `v0.1.0` release. While the core architecture and theming pipeline are feature-complete, you may encounter bugs. Please report them on our [Discord](https://discord.gg/BV8UduvABx) or via GitHub Issues! ---

Installation

### One line installer ```bash curl -fsSL https://raw.githubusercontent.com/Brainitech/Brain_Shell/refs/heads/main/install.sh | bash ``` ### Manual installation ```bash git clone https://github.com/Brainitech/Brain_Shell.git cd Brain_Shell chmod +x install.sh ./install.sh ``` The installer automatically: - ✓ Detects your Linux distribution - ✓ Detects your Window Manager and Hyprland Config - ✓ Backs up your entire `~/.config` - ✓ Installs all required dependencies - ✓ Clones the repository to `~/.local/src/Brain_Shell` - ✓ Updates your Hyprland config - ✓ Creates configuration directories **After installation, restart Hyprland for changes to take effect.** ---

Requirements

> [!IMPORTANT] > **Matugen is required** for dynamic color generation. Brain Shell will not function correctly without it. ### Core Dependencies
Runtime & Rendering - **Hyprland** v0.55+ – Wayland compositor - **Quickshell** – QML shell framework - **Qt6** – Qt6 libraries and QML engine - **qt6ct** – Qt6 theme configuration
System Tools - **PipeWire** – Audio server (pipewire, pipewire-pulse, wireplumber) - **NetworkManager** – Network management - **BlueZ** – Bluetooth stack (bluez, bluez-utils) - **Brightnessctl** – Backlight control - **Mpris** – Media Retrival - **Playerctl** – Player controls - **UPower** – Battery and power info - **libnotify** – Desktop notifications - **Polkit** – Privilege escalation - **wl-clipboard** – Wayland clipboard (wl-copy/wl-paste)
Theming & Wallpaper - **Matugen** – Material You color generation **(REQUIRED)** - **awww** – Wallpaper daemon (Wayland) - **ImageMagick** – Image manipulation
Recording & Utilities - **wf-recorder** – Screen recording (Wayland) - **cava** – Audio visualizer - **slurp** – Region/window selection - **wtype** – Keyboard input emulation - **cliphist** – Clipboard history manager
Hardware Management - **lm_sensors** – CPU temperature & fan monitoring - **rfkill** – Airplane mode control - **envycontrol** – GPU switching (NVIDIA/Intel) - **auto-cpufreq** – CPU frequency scaling - **nbfc-linux** – Laptop fan control
Hyprland Integration - **hyprlock** – Lock screen - **hypridle** – Idle management daemon - **hyprsunset** – Blue light filter - **hyprshutdown** – Graceful shutdown - **xdg-desktop-portal-hyprland** – Portal backend
Fonts - **ttf-jetbrains-mono-nerd** – Primary font (Nerd Font variant) - **ttf-noto-nerd** – Emoji and CJK support
---

Roadmap

### Current (v0.1.0) - [x] Core shell framework - [x] System monitoring dashboard - [x] Keybind editor with live conflict detection - [x] Network management (WiFi, Bluetooth, VPN) - [x] Audio control panel - [x] Screen recording integration - [x] Clipboard manager - [x] Material You color integration - [x] Lua config generation - [x] Professional installer (Arch/NixOS) - [x] Auto-update mechanism ### Upcoming (Post-v0.1.0) - [ ] Scaling on Different Screen-Sizes - [ ] Config Pages for Shell Customization - [ ] Multi-Monitor Support - [ ] Additional theme options - [ ] App launcher enhancements (pinned/recent) - [ ] Unified popup configuration layer - [ ] Extended documentation - [ ] Community themes - [ ] CLI - [ ] More Linux distribution support ---

Known Issues

- **Multi-Monitor Scaling:** Global scaling across mixed-resolution monitors (e.g., 4K paired with 1080p) is currently inconsistent. UI elements may appear misproportioned or poorly sized on non-1080p screens. - **Input Focus Delays:** The App Launcher and Wallpaper popups occasionally fail to capture keyboard focus immediately upon opening. A slight mouse movement is currently required to force focus activation. - **Top Bar Clipping:** Elements within the right notch may become visually clipped if the system tray is expanded and contains an excessive number of active items. - **Shutdown Menu (Hyprshutdown) State:** Canceling a shutdown or logout action can sometimes leave the Hyprland session in an empty state with most applications unintentionally closed. It may also occasionally struggle to terminate all running apps smoothly. ---

Contributing

Brain Shell is actively developed and welcomes contributions! - Found a bug? → [Open an issue](https://github.com/Brainitech/Brain_Shell/issues) - Have an idea? → [Start a discussion](https://github.com/Brainitech/Brain_Shell/discussions) - Want to contribute? → Fork, branch, and submit a pull request ---

Special Thanks

- **[Hyprland Community](https://github.com/hyprwm)** – For creating an exceptional Wayland compositor and fostering an amazing community - **[Quickshell Contributors](https://github.com/quickshell/quickshell)** – For the powerful QML framework that powers this shell - **[Matugen Team](https://github.com/InioX/matugen)** – For Material You color generation technology - **[Wayland Project](https://wayland.freedesktop.org)** – For the modern display protocol foundation - **[Celestial Shell](https://github.com/caelestia-dots/shell)** & **[AX-Shell](https://github.com/Axenide/ax-shell)** — For the inspiration - **[NotCandy001](https://github.com/notcandy001)** — For the installer - **All the Testers & Contributors** — For their time put into testing and suggesting fixes. ---

License

This project is licensed under the MIT License – see the [LICENSE](LICENSE) file for details.