Automated BSPWM Desktop Environment

A complete, automated installation system for a modern tiling window manager desktop environment based on bspwm. ZUI provides a beautiful, functional, and customizable desktop experience with multiple themes and modular installation options.

Design Philosophy

ZUI follows a modular approach that separates UI window manager components from terminal configuration:

• 🖼️ UI Components: Window manager, status bar, compositor, themes, and visual elements
• 💻 Terminal Setup: Shell configuration, prompt theme, CLI tools, and terminal-specific settings
• 🔧 User Choice: Install both together or independently based on your needs

This separation means you can:

• Use ZUI's window manager with your existing terminal setup
• Enhance your terminal with ZUI's configuration while keeping your current window manager
• Install everything together for a complete desktop transformation

Features

🏗️ Modular Architecture

• Component Independence: UI and terminal configurations work separately
• Installation Flexibility: Choose UI-only, terminal-only, or combined setup
• Configuration Preservation: Respects your existing dotfiles and settings
• Easy Maintenance: Update components without affecting others

🎨 Professional Themes

• Multiple Options: Geometric, Galaxy, Nord and Haxor themes included
• Cohesive Design: Matching colors across all components
• Safe Switching: Change themes without losing terminal configurations
• Visual Consistency: Coordinated UI and terminal styling

🖥️ Modern Window Management

• Tiling Layout: Efficient bspwm window manager with intuitive controls
• Smart Bars: Polybar status bars with system monitoring and controls
• Quick Launch: Rofi application launcher and system menus
• Visual Effects: Picom compositor with smooth animations
• Notification System: Clean dunst notifications
• Hardware Detection: Automatic configuration based on your system

💻 Enhanced Terminal Experience

• Powerlevel10k: Beautiful, fast zsh prompt with git integration
• Optimized Zsh: Pre-configured shell with useful aliases and functions
• Independent Installation: Works with any window manager
• Theme Coordination: Matches UI themes when installed together

Included Themes

Theme	Description	Screenshot
Geometric	Geometric theme colors inspired by glowing wireframe aesthetic
Galaxy	Dark theme with purple/blue accents
Nord	Clean Nordic-inspired color scheme
Haxor	Cyberpunk/terminal aesthetic

Components

UI Components (Window Manager)

• Window Manager: bspwm - Binary space partitioning window manager
• Hotkey Daemon: sxhkd - Simple X hotkey daemon
• Status Bar: Polybar - Fast and customizable status bar
• Compositor: Picom - Lightweight compositor for X11
• Application Launcher: Rofi - Window switcher and launcher
• Notifications: Dunst - Lightweight notification daemon
• Wallpaper: Feh - Image viewer and wallpaper setter
• Lock Screen: i3lock-color - Improved screen locker

Terminal Components (Optional)

• Shell: Zsh with enhanced configuration
• Prompt: Powerlevel10k - Fast and customizable prompt
• File Listing: lsd - Modern ls replacement with colors and icons
• File Viewer: bat - Cat with syntax highlighting
• File Manager: ranger - Console file manager
• Editor: Neovim - Hyperextensible text editor
• Fuzzy Finder: fzf - Command-line fuzzy finder
• Plugins: Syntax highlighting, autosuggestions, and productivity enhancements

Prerequisites

System Requirements

• OS: Ubuntu 20.04+ or Debian 11+ (primary support)
• Display Server: X11 (Wayland not supported)
• Memory: At least 2GB RAM recommended
• Storage: ~1GB free space for full installation

Required Privileges

• User account with sudo access
• Internet connection for downloading packages

Installation

Quick Setup

# Check system compatibility
zui.sh check-deps

# Full installation (UI + Terminal)
zui.sh install

# Or specify a theme
zui.sh install -t nord

Modular Installation

UI Only (preserve your terminal setup):

zui.sh install-ui-only

Terminal Only (enhance shell without UI):

zui.sh install-terminal

Step by Step (maximum control):

zui.sh install-deps
zui.sh install-core        # Install UI components
zui.sh install-shell    # Configure shell (optional)
zui.sh install-theme -t galaxy  # Apply theme

🎨 Theme Management

List Available Themes

zui.sh list-themes

Switch Themes

zui.sh install-theme -t geometric

Create New Theme

# Copy existing theme as template
cp -r themes/galaxy themes/mytheme
# Edit configurations in themes/mytheme/

💻 Terminal Configuration

ZUI provides optional terminal enhancement that works independently from UI themes.

Features

• Powerlevel10k: Beautiful, fast zsh prompt
• Enhanced Shell: Zsh with useful plugins and modern tools
• Backup Protection: Preserves existing shell configurations
• Independence: Works with or without ZUI themes

Installation

zui.sh install-shell

🔧 Configuration Management

Configuration Locations

~/.config/bspwm/           # Window manager settings
~/.config/polybar/         # Status bars  
~/.config/sxhkd/           # Keybindings
~/.config/rofi/            # Application launcher
~/.config/picom/           # Compositor effects
~/.zui/                    # ZUI installation directory
~/.zui/shell/              # Default terminal configurations
~/.p10k.zsh               # Your active P10k config (if installed)
~/.zshrc                  # Your active zsh config (if installed)

Terminal Configuration Preservation

ZUI respects your existing terminal setup:

• Existing configurations: If you already have ~/.zshrc or ~/.p10k.zsh, theme installation won't overwrite them
• Clean installations: New users get default terminal configurations automatically
• Modular updates: You can update UI themes without affecting terminal settings
• Independent terminal: Terminal configuration works with or without ZUI themes

Switching Between Themes

# Safely switch themes (preserves terminal config)
zui.sh install-theme -t geometric
zui.sh install-theme -t galaxy
zui.sh install-theme -t nord
zui.sh install-theme -t haxor

⌨️ Default Keybindings

Shortcut	Action
Super + Esc	Show keybinds
Super + Return	Open terminal
Super + D	Application launcher
Super + Shift + D	Command launcher
Super + X	Window switcher
Super + Q	Power menu
Super + L	Lock screen
Super + N	Network menu
Alt + Tab	Cycle windows
Super + 1-9	Switch to desktop
Super + Shift + 1-9	Move window to desktop

Window Management

Shortcut	Action
Super + H/J/K/L	Focus window (left/down/up/right)
Super + Shift + H/J/K/L	Move window
Super + Ctrl + H/J/K/L	Resize window
Super + F	Toggle fullscreen
Super + T	Toggle tiled/floating
Super + W	Close window

🛠️ Customization

Configuration Files

• System Config: ~/.zui/core/system/config.yml
• Shell Config: ~/.zui/shell/
• Theme Configs: ~/.config/ (bspwm, polybar, rofi, etc.)

Multi-Monitor Setup

Edit ~/.zui/core/system/config.yml:

monitors:
  HDMI-1:
    resolution: 1920x1080
    main: 1
    workspaces: [1, 2, 3, 4, 5]
  eDP-1:
    resolution: 1920x1080
    position: left
    workspaces: [6, 7, 8, 9, 0]

🔄 Maintenance

Update ZUI

git pull origin master
zui.sh install  # Re-run installation

Backup Configuration

zui.sh backup
# or specify backup location
zui.sh backup -b /path/to/backup

Restore Configuration

zui.sh restore -b /path/to/backup

Clean Temporary Files

zui.sh clean

🗑️ Uninstallation

UI-Focused Removal (Recommended)

zui.sh uninstall

This will:

• Remove ZUI directory and UI configurations
• Remove system rules and desktop entries
• Preserve terminal configurations (.zshrc, .p10k.zsh, shell tools)
• Restore backed up configurations (if available)
• Keep user data and most installed packages

Complete Terminal Cleanup (Optional)

If you also want to remove terminal configurations:

# After running make uninstall, manually remove:
rm ~/.zshrc ~/.p10k.zshmake
rm -rf ~/powerlevel10k/

# Restore backups if they exist
if [ -f ~/.zshrc.backup ]; then mv ~/.zshrc.backup ~/.zshrc; fi
if [ -f ~/.p10k.zsh.backup ]; then mv ~/.p10k.zsh.backup ~/.p10k.zsh; fi

Manual Package Cleanup

If you need to remove installed packages (be careful!):

# Remove window manager components (optional)
sudo apt remove bspwm sxhkd polybar rofi dunst picom

# Remove development tools (be careful!)
sudo apt remove build-essential cmake

# Remove terminal tools (optional)
sudo apt remove zsh lsd bat ranger neovim fzf

Note: The default uninstall preserves terminal configurations since they're user-specific and may be used outside of ZUI.

🤝 Contributing

We welcome contributions! Here's how you can help:

Adding New Themes

1. Copy existing theme: cp -r themes/galaxy themes/newtheme
2. Customize configurations in themes/newtheme/
3. Test theme: make install-theme THEME=newtheme
4. Submit pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Special thanks to the developers and communities behind the following tools and projects that make ZUI possible:

UI Components

• bspwm - Window manager
• sxhkd - Hotkey daemon
• polybar - Status bar
• picom - Compositor
• rofi - Application launcher
• dunst - Notification daemon
• feh - Wallpaper setter
• i3lock-color - Lock screen

Terminal Components

• zsh - Shell
• powerlevel10k - Prompt theme
• lsd - Modern ls replacement
• bat - File viewer
• ranger - Console file manager
• neovim - Text editor
• fzf - Fuzzy finder

All contributors - Community improvements

Note: This project is designed for X11 environments. Wayland support may be added in future versions.