🍭 FlavourSwitch - Ultimate QuickShell Theme Manager

Seamlessly switch between QuickShell configurations with style!

📥 Installation • 🚀 Quick Start • 📖 Documentation • 🤝 Contributing

✨ What is FlavourSwitch?

FlavourSwitch is a powerful, lightweight CLI tool that revolutionizes how you manage multiple QuickShell configurations (flavours). Built for Hyprland users who love customizing their desktop experience, it provides instant theme switching with intelligent keybind management and a beautiful interactive panel.

📸 Screenshots & Previews

🎨 Interactive Theme Panel

🖱️ Click to view full-size Theme Panel

FlavourSwitch Interactive Panel Full View

Beautiful, responsive theme selection panel with live previews and smooth animations

🔍 Click to zoom into Panel Details

Detailed view of theme cards, search functionality, and control buttons

🖥️ Desktop Integration Examples

Theme Showcase Gallery

🎭 Click to explore Theme Gallery

Caelestia Theme

Modern, clean aesthetic with subtle gradients

Noctalia Theme

Dark, mysterious vibe with deep blues

DMS Theme

Minimalist design with focus on functionality

Xenon Theme

Neon cyberpunk style with vibrant accents

Before vs After Comparisons

⚡ Click to see Transformation

BEFORE
Default Hyprland + QuickShell setup

AFTER
Enhanced with FlavourSwitch themes

⚡ Command Line Interface

💻 Click to see Full Terminal Demo

Complete terminal session showing commands, auto-completion, and theme switching

📋 Click to see Help System

Comprehensive help system with detailed command reference

🎛️ Configuration & Setup

⚙️ Click to see Configuration Files

Detailed view of configuration files and keybind management

🌟 Key Features

🎯 Core Functionality

🚀 Instant Switching: Switch between QuickShell themes in milliseconds
🎨 Theme Management: Support for unlimited custom themes/flavours
🔄 Smart Cycling: Automatically cycle through available themes
📱 Interactive Panel: Beautiful GUI panel for theme selection

⚙️ Advanced Features

🛠️ Intelligent Keybind Management: Automatic conflict resolution and keybind switching
🔧 Auto-Fix System: Self-healing configuration that detects and fixes issues
📋 Shell Completions: Full bash, zsh, and fish completion support
🎛️ Custom Keybinds: Configurable hotkeys for all operations
📊 Status Monitoring: Real-time theme status and installation checks

🏗️ Technical Excellence

⚡ Lightning Fast: Minimal resource usage, instant response
🔒 Type Safe: Written in Go with comprehensive error handling
📦 Easy Installation: Multiple installation methods (CMake, Go, AUR)
🔄 Auto Updates: Configuration auto-reload and live updates
🧪 Well Tested: Comprehensive test coverage and CI/CD pipeline

🚀 Quick Start

Prerequisites

Go 1.25.4+ - For building from source
Hyprland - Window manager
QuickShell - Shell framework
CMake 3.15+ (optional) - For CMake builds

⚡ 3-Step Setup

# 1. Clone and enter directory
git clone https://github.com/CodewithEvilxd/flavourswitch.git
cd flavourswitch

# 2. Run setup script
chmod +x setup.sh && ./setup.sh

# 3. Start using!
flavourswitch --help

🎯 First Theme Switch

# List available themes
flavourswitch list

# Switch to your favorite theme
flavourswitch apply caelestia

# Open interactive panel
flavourswitch panel

📦 Installation

🎯 Recommended: Automated Setup

git clone https://github.com/CodewithEvilxd/flavourswitch.git
cd flavourswitch
chmod +x setup.sh
./setup.sh

🛠️ Manual Installation Options

Option 1: CMake Build (Recommended for Linux)

# Build
mkdir build && cd build
cmake .. && make

# Install system-wide
sudo make install

# Initial setup
flavourswitch exp-setup

Option 2: Go Build

# Build binary
go build -o flavourswitch .

# Install
sudo cp flavourswitch /usr/local/bin/
sudo cp man/flavourswitch.1 /usr/local/share/man/man1/

# Install completions
sudo cp completions/flavourswitch.bash /usr/share/bash-completion/completions/
sudo cp completions/flavourswitch.zsh /usr/share/zsh/site-functions/
sudo cp completions/flavourswitch.fish /usr/share/fish/vendor_completions.d/

# Install QML interface
sudo mkdir -p /etc/xdg/quickshell/flavourswitch
sudo cp -r quickshell/* /etc/xdg/quickshell/flavourswitch/

Option 3: AUR Package (Arch Linux)

# Using yay
yay -S flavourswitch-git

# Using paru
paru -S flavourswitch-git

# Using pikaur
pikaur -S flavourswitch-git

# Manual build
git clone https://aur.archlinux.org/flavourswitch-git.git
cd flavourswitch-git
makepkg -si

AUR Package Features:

Automatic dependency management
System integration with pacman
Post-install setup messages
Configuration file examples in /usr/share/doc/flavourswitch/
Shell completions for bash, zsh, and fish

🔧 Post-Installation Setup

FlavourSwitch will automatically run initial setup on first use:

flavourswitch exp-setup

This creates:

~/.config/flavourswitch/ - Configuration directory
~/.cache/flavourswitch/ - Cache directory
~/.flavourswitch_state - Current theme state
Hyprland configuration integration

💡 Usage Guide

🎮 Basic Commands

Command	Description	Example
`flavourswitch`	Cycle to next theme	`flavourswitch`
`flavourswitch apply <theme>`	Switch to specific theme	`flavourswitch apply caelestia`
`flavourswitch list`	Show all themes	`flavourswitch list`
`flavourswitch current`	Show active theme	`flavourswitch current`
`flavourswitch panel`	Open theme panel	`flavourswitch panel`
`flavourswitch reload`	Reload keybinds	`flavourswitch reload`

🎨 Advanced Usage

Theme Management

# Apply current theme again (useful after config changes)
flavourswitch apply --current

# Switch only keybinds without changing theme
flavourswitch switch-keybinds noctalia-shell

# Force setup (overwrite existing config)
flavourswitch exp-setup --force

Interactive Panel

# Toggle panel visibility
flavourswitch panel

# Panel features:
# - Visual theme previews
# - One-click theme switching
# - Search and filter themes
# - Keyboard navigation

Status Checking

# List themes with installation status
flavourswitch list --status

# Check current theme
flavourswitch current

# Get detailed help
flavourswitch --help

⌨️ Keyboard Shortcuts

Shortcut	Action	Configurable
`Super + Alt + P`	Open theme panel	✅
`Tab`	Cycle themes	❌
`Enter`	Apply selected theme	❌
`Escape`	Close panel	❌

⚙️ Configuration

📁 Configuration Files

FlavourSwitch uses JSON configuration stored in ~/.config/flavourswitch/config.json:

{
  "flavours": ["ii", "caelestia", "noctalia-shell", "dms", "xenon"],
  "unbinds": true,
  "keybinds": {
    "ii": "default",
    "caelestia": "caelestia.conf",
    "noctalia-shell": "noctalia.conf",
    "dms": "dms.conf",
    "xenon": "xenon.conf"
  },
  "panel_keybind": "Super+Alt, P"
}

🔧 Configuration Options

Basic Settings

flavours (required): Array of available theme names
panel_keybind (optional): Hotkey to open theme panel (default: "Super+Alt, P")

Advanced Settings

unbinds: Enable/disable automatic keybind unbinding
keybinds: Map themes to keybind configuration files

🎨 Theme Structure

~/.config/flavourswitch/
├── config.json           # Main configuration
└── keybinds/            # Keybind files
    ├── caelestia.conf
    ├── noctalia.conf
    ├── un binds.conf
    └── ...

🔄 Auto-Generated Files

FlavourSwitch automatically manages:

~/.cache/flavourswitch/flavourswitch.conf - Generated Hyprland config
~/.flavourswitch_state - Current theme state
Hyprland integration in ~/.config/hypr/hyprland.conf

🎨 Creating Themes

🏗️ Theme Development Guide

1. Create Theme Directory

# Create theme directory structure
mkdir -p ~/.config/quickshell/your-theme
cp -r /etc/xdg/quickshell/caelestia/* ~/.config/quickshell/your-theme/

2. Customize QML Files

Edit ~/.config/quickshell/your-theme/shell.qml:

// Customize colors, layout, widgets
Rectangle {
    color: "#your-background-color"
    // ... your customizations
}

3. Add Keybinds (Optional)

Create ~/.config/flavourswitch/keybinds/your-theme.conf:

# Hyprland keybind definitions
bind = SUPER, Return, exec, your-terminal
bind = SUPER, D, exec, your-app-launcher

4. Register Theme

Add to ~/.config/flavourswitch/config.json:

{
  "flavours": ["ii", "caelestia", "your-theme"],
  "keybinds": {
    "your-theme": "your-theme.conf"
  }
}

5. Test Theme

flavourswitch apply your-theme
flavourswitch panel  # Verify in theme picker

🎨 Theme Best Practices

Consistent Naming: Use lowercase with hyphens
Icon Requirements: Provide SVG icons in quickshell/icons/
Color Schemes: Follow Catppuccin or similar standards
Documentation: Include README in theme directory
Testing: Test across different screen resolutions

🔧 Troubleshooting

🚨 Common Issues

"Command not found"

# Check if installed
which flavourswitch

# Reinstall if missing
sudo cp flavourswitch /usr/local/bin/

Panel not opening

# Check Hyprland integration
grep "flavourswitch" ~/.config/hypr/hyprland.conf

# Reload Hyprland config
hyprctl reload

Theme not switching

# Check theme installation
flavourswitch list --status

# Verify theme files exist
ls -la ~/.config/quickshell/your-theme/

Keybinds not working

# Reload keybinds
flavourswitch reload

# Check generated config
cat ~/.cache/flavourswitch/flavourswitch.conf

🐛 Debug Mode

Enable verbose logging:

# Run with debug info
flavourswitch apply caelestia --verbose

📞 Getting Help

Issues: GitHub Issues
Discussions: GitHub Discussions
Discord: raj.dev_

🤝 Contributing

💻 Development Setup

# Fork and clone
git clone https://github.com/your-username/flavourswitch.git
cd flavourswitch

# Install dependencies
go mod tidy

# Build and test
go build -o flavourswitch .
go test ./...

# Run linters
golangci-lint run

📝 Contribution Guidelines

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
Open a Pull Request

🧪 Testing

# Run all tests
go test ./...

# Run with coverage
go test -cover ./...

# Integration testing
./test/integration.sh

📖 Code Standards

Follow Go conventions and effective Go practices
Add tests for new features
Update documentation
Maintain backwards compatibility

📦 AUR Package Details

Package Information

Package Name: flavourswitch-git
Maintainer: Nishant Gaurav CodewithEvilxd@gmail.com
Upstream URL: https://github.com/CodewithEvilxd/flavourswitch
License: GPL-3.0
Dependencies: glibc, hyprland
Optional Dependencies:
- quickshell: For shell configurations and themes
- fish: For fish shell completions
- zsh: For zsh shell completions
- bash-completion: For bash shell completions

Installation Features

Automatic Setup: Post-install script guides initial configuration
System Integration: Proper pacman integration with conflicts/provides
Documentation: Includes example configs in /usr/share/doc/flavourswitch/
Shell Completions: Automatic installation for all supported shells
Man Pages: System man page integration

Package Files

/usr/bin/flavourswitch                    # Main binary
/usr/share/man/man1/flavourswitch.1       # Manual page
/usr/share/bash-completion/completions/   # Bash completions
/usr/share/zsh/site-functions/            # Zsh completions
/usr/share/fish/vendor_completions.d/     # Fish completions
/usr/share/doc/flavourswitch/             # Documentation & examples

📄 License

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

FlavourSwitch - Ultimate QuickShell Theme Manager
Copyright (C) 2026 Nishant Gaurav

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

🙏 Acknowledgments

🛠️ Built With

Go - Programming language
Cobra - CLI framework
Qt/QML - GUI framework
Hyprland - Window manager

👥 Inspiration & Thanks

QuickShell Community - For the amazing shell framework
Catppuccin - For beautiful color schemes
Hyprland Contributors - For the best Wayland compositor

🌟 Special Thanks

Original Author: For creating the foundation
Contributors: For improving and maintaining the project
Community: For feedback, bug reports, and feature requests

🎉 Happy Theming!

Made with ❤️ by Nishant Gaurav

⭐ Star this repo if you find it useful!

⬆️ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.github/workflows		.github/workflows
AUR		AUR
cmd		cmd
completions		completions
example		example
man		man
quickshell		quickshell
utils		utils
.gitignore		.gitignore
CMakeLists.txt		CMakeLists.txt
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
cmake_uninstall.cmake.in		cmake_uninstall.cmake.in
go.mod		go.mod
go.sum		go.sum
main.go		main.go
setup.sh		setup.sh

Folders and files

Latest commit

History

Repository files navigation