wmswitch

⚡ Beta v0.1.0

Unified configuration manager for tiling window managers

Maintain a single TOML configuration file and generate native configs for i3, Hyprland, and AeroSpace. Profile management, conflict detection, and migration tools.

GitHub Get Started

Quick Start

wmswitch eliminates duplicate config files by providing a single TOML configuration that generates native configs for multiple window managers.

Interactive Setup

$wmswitch wizard ~/.config/wmswitch/config.toml

Welcome to wmswitch configuration wizard! Configure your applications: Terminal [alacritty]: Launcher [rofi -show drun]: Browser [firefox]: Configuration saved to ~/.config/wmswitch/config.toml

$wmswitch generate ~/.config/wmswitch/config.toml

Generating configs... ✓ i3 config → ~/.config/i3/config ✓ Hyprland config → ~/.config/hypr/hyprland.conf Complete!

Installation

From RPM

DNF

$sudo dnf install wmswitch

$wmswitch version

wmswitch version 0.1.0

From Source

Make

$git clone https://github.com/tenseleyFlow/wmswitch.git

$cd wmswitch && make release

$sudo install bin/wmswitch /usr/local/bin/

Dependencies

Build Requirements

gcc - GNU C Compiler
make - Build automation
C99 standard library

Runtime Requirements

At least one: i3, Hyprland, or AeroSpace
No external dependencies (statically linked TOML parser)

First Steps

Create your first configuration using the wizard:

Wizard

$wmswitch wizard ~/.config/wmswitch/config.toml

$wmswitch validate ~/.config/wmswitch/config.toml

Validating configuration... ✓ No conflicts detected ✓ 4 workspaces defined ✓ 12 keybindings configured Configuration is valid

$wmswitch --backup generate ~/.config/wmswitch/config.toml

Creating backups... Generating configs... ✓ Complete!

Configuration Format

wmswitch uses TOML for configuration. Define workspaces and keybindings once, generate for all window managers.

Basic Configuration

# Workspace definitions
[workspaces.dev]
number = 1
monitor = "main"

[workspaces.web]
number = 2
monitor = "main"

[workspaces.comm]
number = 3
monitor = "secondary"

# Universal keybindings (all WMs)
[keybinds]
"mod+1" = "workspace 1"
"mod+2" = "workspace 2"
"mod+3" = "workspace 3"
"mod+return" = "exec alacritty"
"mod+d" = "exec rofi -show drun"
"mod+f" = "fullscreen toggle"
"mod+shift+space" = "toggle floating"

WM-Exclusive Sections

Add window-manager-specific keybindings and settings:

# i3-specific keybindings
[keybinds.i3.exclusive]
"mod+shift+q" = "kill"
"mod+shift+c" = "reload"
"mod+shift+r" = "restart"

# Hyprland-specific keybindings
[keybinds.hyprland.exclusive]
"mod+q" = "killactive"
"mod+m" = "exit"
"mod+v" = "togglefloating"

# Workspace-specific WM settings
[workspaces.dev.i3.exclusive]
layout = "tabbed"

[workspaces.dev.hyprland.exclusive]
rounding = 15
gapsin = 10
gapsout = 15

Keybind Syntax

mod+ - Super/Windows key
ctrl+ - Control key
shift+ - Shift key
alt+ - Alt key

wmswitch automatically translates these to WM-specific syntax:

Universal        → i3              → Hyprland
"mod+1"          → bindsym $mod+1  → bind = $mainMod, 1
"shift+return"   → bindsym Shift+Return → bind = SHIFT, Return

Configuration Includes

Modular configs via includes:

# Main config.toml
include = [
    "~/.config/wmswitch/common.toml",
    "~/.config/wmswitch/work-specific.toml"
]

Config Locations

~/.config/wmswitch/config.toml - Main configuration
~/.config/wmswitch/profiles/ - Profile configurations
~/.config/i3/config - Generated i3 config
~/.config/hypr/hyprland.conf - Generated Hyprland config
~/.config/aerospace/aerospace.toml - Generated AeroSpace config

Overview

wmswitch is a unified configuration manager for tiling window managers. Maintain one TOML configuration file and generate native configs for multiple WMs.

Key Features

Single source of truth for all window managers
Automatic config generation for i3, Hyprland, AeroSpace
Conflict detection and validation
Profile management for different use cases
Migration tools from existing configs
Interactive configuration wizard

Window Manager Support

Option	Type	Default	Description
`i3`	WM	Full	Workspaces, keybinds, layouts, floating
`Hyprland`	WM	Full	Workspaces, keybinds, animations, gaps
`AeroSpace`	WM	Framework	Basic support (in development)

Auto-Detection

wmswitch automatically detects your current window manager via environment variables and X11/Wayland properties.

System Overview

wmswitch is written in C with a modular architecture separating parsing, validation, and generation concerns.

wmswitch/
├── src/
│   ├── main.c              # Entry point
│   ├── core/               # Core functionality
│   │   ├── generator.c     # Generation orchestration
│   │   ├── validator.c     # Validation & conflicts
│   │   ├── wizard.c        # Interactive setup
│   │   ├── profiles.c      # Profile management
│   │   └── migration.c     # Config import
│   ├── generators/         # WM-specific generators
│   │   ├── i3_generator.c
│   │   ├── hyprland_generator.c
│   │   └── aerospace_generator.c
│   └── parsers/
│       └── toml_config.c   # TOML parsing
└── lib/tomlc99/            # Embedded TOML parser

CLI Reference

Complete command-line interface reference for wmswitch.

Core Commands

Option	Type	Default	Description
`wmswitch generate <file>`	command	-	Generate WM configs from TOML file
`wmswitch validate <file>`	command	-	Validate TOML configuration
`wmswitch wizard [output]`	command	-	Interactive setup wizard
`wmswitch detect`	command	-	Auto-detect current window manager
`wmswitch version`	command	-	Show version information
`wmswitch help`	command	-	Display help message

Profile Commands

Option	Type	Default	Description
`wmswitch profile list`	command	-	List all available profiles
`wmswitch profile create <name> <desc>`	command	-	Create new profile
`wmswitch profile switch <name>`	command	-	Activate a profile
`wmswitch profile delete <name>`	command	-	Remove a profile
`wmswitch profile generate <name>`	command	-	Generate from profile

Migration Commands

Option	Type	Default	Description
`wmswitch migrate i3 <output>`	command	-	Migrate from i3 config
`wmswitch migrate hyprland <output>`	command	-	Migrate from Hyprland
`wmswitch migrate auto <output>`	command	-	Auto-detect and migrate

Global Options

Option	Type	Default	Description
`-h, --help`	flag	false	Show help message
`-v, --verbose`	flag	false	Enable verbose output
`-q, --quiet`	flag	false	Suppress non-error output
`-d, --debug`	flag	false	Enable debug output
`--dry-run`	flag	false	Preview without writing files
`--backup`	flag	false	Create .wmswitch.backup files

Usage Examples

Basic Workflow

$wmswitch wizard ~/.config/wmswitch/config.toml

$wmswitch validate ~/.config/wmswitch/config.toml

$wmswitch --backup --dry-run generate ~/.config/wmswitch/config.toml

$wmswitch generate ~/.config/wmswitch/config.toml

Troubleshooting

Common issues and solutions when using wmswitch.

Validation Errors

Problem: Configuration validation fails.

Solution: Run validator for detailed errors:

Validation

$wmswitch --verbose validate config.toml

❌ Error: Duplicate workspace number: 2 workspace 'web' and 'media' both use number 2 ❌ Error: Duplicate keybind: mod+1 Conflicts in 'i3' section

Generated configs not applied

Problem: Changes don't take effect.

Solution: Reload or restart window manager:

Reload

$i3-msg reload

# For i3

$hyprctl reload

# For Hyprland

Failed to open config file

Problem: Can't read configuration file.

Solutions:

Check file path is correct
Verify file permissions are readable
Ensure file exists: ls -l config.toml

Keybind conflicts

Problem: Same key defined multiple times.

Solution: Use WM-exclusive sections:

[keybinds.i3.exclusive]
"mod+q" = "kill"

[keybinds.hyprland.exclusive]
"mod+q" = "killactive"

Backup not created

Problem: Existing configs not backed up.

Solution: Use --backup flag:

Backup

$wmswitch --backup generate config.toml

Creating backups... ✓ ~/.config/i3/config.wmswitch.backup Generating configs...

Migration fails

Problem: Can't import existing config.

Solutions:

Check source config path is correct
Verify source config is valid for its WM
Use migrate auto for auto-detection
Review migration output for partial success

Testing

Run the test suite to verify installation:

Testing

$make test

Running tests... ✓ Version command ✓ Help command ✓ Config validation ✓ Dry-run generation ✓ Config generation ✓ i3 config content ✓ Hyprland config content ✓ Backup functionality All tests passed!

$make smoke-test

Quick functionality check...

Getting Help

GitHub Issues: Report bugs or request features
Built-in Help: wmswitch help
Examples: Check examples/ directory in repo

wmswitch

Quick Start

Installation

From RPM

From Source

Dependencies

Build Requirements

Runtime Requirements

First Steps

Configuration Format

Basic Configuration

WM-Exclusive Sections

Keybind Syntax

Configuration Includes

Config Locations

Overview

Key Features

Window Manager Support

Auto-Detection

Configuration Format

Workspaces

Keybindings

WM-Exclusive Sections

i3 Exclusive

Hyprland Exclusive

Profile Management

Profile Storage

Migration Tools

System Overview

Module Structure

Generator System

Generator Interface

Validator

Validation Checks

TOML Parser

Data Structures

Build System

CLI Reference

Core Commands

Profile Commands

Migration Commands

Global Options

Usage Examples

Troubleshooting

Validation Errors

Generated configs not applied

Failed to open config file

Keybind conflicts

Backup not created

Migration fails

Testing

Getting Help