Qswitch

---

Showcase Video

qswitch.mp4

📋 Table of Contents

• Features
• Installation
• Usage
• Configuration
• Shell Completions
• Uninstall
• Contribution
• Files

---

Features

• Seamless Flavour Switching: Easily switch between different QuickShell configurations
• Keybind Management: Automatic keybind switching with conflict resolution
• Interactive Panel: Toggle a quick switch panel for visual selection
• Autofix: Automatically detects and fixes common configuration issues
• Shell Completions: Supports bash, zsh, and fish completions
• Lightweight: Minimal dependencies, fast and efficient

---

Installation

Prerequisites

• Go 1.25.4 or later
• CMake 3.15 or later (optional, for CMake build)
• Hyprland and QuickShell installed

Quick Setup (Recommended)

1. Clone the repository:

   git clone https://github.com/MannuVilasara/qswitch.git
   cd qswitch

2. Make setup script executable and run:

   chmod +x setup.sh
   ./setup.sh

This will build and install qswitch using CMake, and run the initial setup.

Manual Installation

Click to expand manual installation options

CMake Build

1. Clone the repository:

   git clone https://github.com/MannuVilasara/qswitch.git
   cd qswitch

2. Build the project:

   mkdir build
   cd build
   cmake ..
   make

3. Install system-wide (requires root):

   sudo make install

   This installs:

   • The qswitch binary to /usr/local/bin
   • Man page to /usr/local/share/man/man1
   • Shell completions to appropriate directories
   • shell.qml to /etc/xdg/quickshell/qswitch/

Go Build

1. Clone the repository:

   git clone https://github.com/MannuVilasara/qswitch.git
   cd qswitch

2. Build and install:

   go build -o qswitch .
   sudo cp qswitch /usr/local/bin/
   sudo cp man/qswitch.1 /usr/local/share/man/man1/
   sudo cp completions/qswitch.bash /usr/share/bash-completion/completions/qswitch
   sudo cp completions/qswitch.zsh /usr/share/zsh/site-functions/_qswitch
   sudo cp completions/qswitch.fish /usr/share/fish/vendor_completions.d/qswitch.fish
   sudo mkdir -p /etc/xdg/quickshell/qswitch
   sudo cp -r quickshell/* /etc/xdg/quickshell/qswitch

Initial Setup

When you first run qswitch, it will check for setup and run autofix if needed:

qswitch exp-setup

This will:

1. Create necessary directories (~/.config/qswitch, ~/.cache/qswitch)
2. Create the state file ~/.switch_state
3. Generate a default ~/.config/qswitch/config.json
4. Append source=~/.cache/qswitch/qswitch.conf to your ~/.config/hypr/hyprland.conf (if not already present)
5. Remove any incorrect source lines (e.g., from old cache paths)

You can force the setup (even if files exist) with:

qswitch exp-setup --force

The autofix feature automatically detects and fixes common configuration issues.

---

Usage

Command Examples

Command	Description
qswitch	Cycle to the next flavour (runs autofix if needed)
qswitch apply <flavour>	Switch to a specific flavour
qswitch apply --current	Re-apply current flavour
qswitch list	List all available flavours
qswitch current	Show current active flavour
qswitch panel	Toggle the quick switch panel
qswitch reload	Reload keybinds
qswitch switch-keybinds <flavour>	Switch only the keybinds for a specific flavour
qswitch exp-setup	Run the initial setup
qswitch --help	Show help information

Example Usage

# Switch to the 'caelestia' flavour
qswitch apply caelestia

# List all flavours
qswitch list
# Output: ii, caelestia, noctalia-shell, dms

# Check current flavour
qswitch current
# Output: caelestia

---

Configuration

Configuration is stored in `~/.config/qswitch/config.json`. Here's an example:

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

Configuration Options

• flavours: Array of available QuickShell flavours
• unbinds (Optional): Boolean. If true, sources ~/.config/qswitch/keybinds/unbinds.conf before applying flavour-specific keybinds (except for "default" flavour). Useful for unbinding conflicting keys
• keybinds: Object mapping each flavour to a keybind file in ~/.config/qswitch/keybinds/. Use "default" for the base configuration
• panel_keybind (Optional): The keybind to open the QuickSwitch panel. Defaults to "Super+Alt, P"

Keybind files (e.g., caelestia.conf) contain Hyprland keybind definitions.

The tool generates ~/.cache/qswitch/qswitch.conf with the appropriate source and bind commands, which is then sourced in ~/.config/hypr/hyprland.conf.

---

Shell Completions

Qswitch supports shell completions for bash, zsh, and fish. The setup script installs them automatically, or you can install them manually:

• Bash: Source completions/qswitch.bash or copy to /usr/share/bash-completion/completions/
• Zsh: Source completions/qswitch.zsh or copy to /usr/share/zsh/site-functions/
• Fish: Source completions/qswitch.fish or copy to /usr/share/fish/vendor_completions.d/

---

Uninstall

CMake Uninstall

If installed via CMake:

cd build
sudo make uninstall

This will remove the binary, man page, completions, and QML files.

Manual Uninstall

Remove the following files manually:

• /usr/local/bin/qswitch
• /usr/local/share/man/man1/qswitch.1
• Shell completion files in their respective directories
• /etc/xdg/quickshell/qswitch/

Also remove user configuration:

• ~/.config/qswitch/
• ~/.cache/qswitch/
• ~/.switch_state

---

Contribution

Contributions are welcome! Please see CONTRIBUTING.md for details.

---

Files

File/Directory	Description
~/.switch_state	Stores the current active flavour
~/.config/qswitch/config.json	Main configuration file
~/.config/qswitch/keybinds/	Directory containing keybind configuration files
~/.cache/qswitch/qswitch.conf	Generated configuration file (sourced in hyprland.conf)
/etc/xdg/quickshell/qswitch/shell.qml	Panel QML file for the QuickSwitch interface

---

Support