⚡ Snappy Switcher

A blazing-fast, context-aware Alt+Tab window switcher for Hyprland

The window switcher that actually understands your workflow

Pure C · Wayland Layer Shell · Zero dependencies on Electron or GTK runtimes

Key Features

Installation

Arch Linux (AUR)

yay -S snappy-switcher

paru -S snappy-switcher

git clone https://github.com/OpalAayan/snappy-switcher.git
cd snappy-switcher
makepkg -si

sudo dnf install wayland-devel cairo-devel pango-devel json-c-devel libxkbcommon-devel glib2-devel librsvg2-devel wayland-protocols-devel

Nix / NixOS

nix profile install github:OpalAayan/snappy-switcher

nix run github:OpalAayan/snappy-switcher

# flake.nix
{
  inputs.snappy-switcher.url = "github:OpalAayan/snappy-switcher";
}

# configuration.nix
environment.systemPackages = [
  inputs.snappy-switcher.packages.${pkgs.system}.default
];

Manual Build

# Arch
sudo pacman -S wayland cairo pango json-c libxkbcommon glib2 librsvg

# Build & install
make
sudo make install

# Or install for current user only
make install-user

Quick Start

1. Setup Configuration

snappy-install-config

This copies themes to ~/.config/snappy-switcher/themes/ and creates config.ini.

2. Add to Hyprland Config

Add these to ~/.config/hypr/hyprland.lua. The --mod flag must match the modifier used in the bind.

-- Start daemon on login
hl.exec_cmd("snappy-switcher --daemon")

-- Alt+Tab (standard MRU)
hl.bind("ALT + Tab", hl.dsp.exec_cmd("snappy-switcher next --mod alt"))

-- Super+Tab (workspace-filtered)
hl.bind("SUPER + TAB", hl.dsp.exec_cmd("snappy-switcher next --workspace --mod super"))

Hyprland v0.55+ uses Lua config (hyprland.lua), though it will work on older version of hyprland or using (hyprland.conf) on v0.55.x

For Hyprlang

# --- (Snappy Switcher) ---
#exec-once = snappy-wrapper 
exec-once = snappy-switcher --daemon
# Alt+Tab: Global window cycling
bindd = ALT, Tab, Snappy Switcher Next, exec, snappy-switcher next --mod alt
# Super+Tab: Workspace-local window cycling
bindd = SUPER, Tab, Snappy Switcher Workspace Next, exec, snappy-switcher next --workspace --mod super

3. Done

Press your configured bind to see it in action.

Commands

--mod --workspace --silent and --linear are flags and should be used with this commands

Flags

Flags can be combined with next, prev, and toggle.

--mod <key>

Tells the daemon which key to watch for release so it can dismiss the switcher.

Literally use it with any fucking key you want!!!, its a WINDOW SWITCHER not any freaky ALT + TAB

Rules:

• The --mod value must match the key used in your compositor bind. A mismatch triggers a CONFIG ERROR banner.
• If --mod is omitted, the switcher opens in toggle mode -- no dismiss-on-release. Close with Escape, Enter, or snappy-switcher toggle.
• The engine handles rapid taps correctly: if you release the modifier before the compositor delivers the first event, it auto-dismisses instead of throwing a false error.

just plz set bind 1st key and mod same key or you will be blessed with scary banners i made

--workspace

Filter the window list to the currently active workspace.

--silent

Perform an instant MRU switch without creating any Wayland UI. The Cairo rendering pipeline is bypassed entirely — the daemon queries the window list, picks the target, and calls activate_window() directly. If the GUI panel is already open, it is torn down before the silent switch executes.

--linear

Use deterministic workspace/address sorting instead of MRU order. Windows are ordered by workspace ID first, then by Hyprland address. Combinable with --silent for headless deterministic cycling.

Examples

# Standard Alt+Tab with GUI
snappy-switcher next --mod alt

# Workspace-filtered Super+Tab
snappy-switcher next --workspace --mod super

# Instant MRU switch, no UI
snappy-switcher next --silent

# Deterministic linear cycle, no UI
snappy-switcher next --silent --linear

# Space as dismiss key
snappy-switcher next --mod space

# Toggle mode (no modifier dismiss)
snappy-switcher toggle

Theme Gallery

All 15 themes included out of the box. Change one line in your config.

Snappy Slate Default	Catppuccin Mocha	Catppuccin Latte
Catppuccin Frappe	Tokyo Night	Nord
Nordic	Dracula	Gruvbox Dark
Rose Pine	Cyberpunk	Grovestorm
Stormlight	Liquid Glass White	Liquid Glass Black

Change Theme

[theme]
name = catppuccin-mocha.ini

If name doesnt match the file you made or left blank, it will switch to a default ugly theme

[general]
mode = context
follow_monitor = true
show_workspace_badge = true
sticky_mode = false
[theme]
name = stormlight.ini
border_width = 2
corner_radius = 15
[layout]
card_width = 145
card_height = 135
card_gap = 10
padding = 10
max_cols = 5
icon_size = 57
icon_radius = 15       
error_font_size = 11  
[icons]
theme = Tela-dracula
fallback = Tela-dracula
show_letter_fallback = true
[font]
family = FiraCode Nerd Font
weight = Bold
title_size = 10
icon_letter_size = 24

Full Configuration Documentation →

Hyprland Integration

Lua Config (v0.55+)

-- ── Snappy Switcher ──
hl.exec_cmd("snappy-switcher --daemon")

-- Alt+Tab: standard MRU switching
hl.bind("ALT + Tab", hl.dsp.exec_cmd("snappy-switcher next --mod alt"),
  { description = "Snappy Switcher" })

-- Super+Tab: workspace-filtered switching
hl.bind("SUPER + TAB", hl.dsp.exec_cmd("snappy-switcher next --workspace --mod super"),
  { description = "Snappy Switcher (Workspace)" })

-- Silent instant switch (no UI) + linear
-- hl.bind("CTRL + W", hl.dsp.exec_cmd("snappy-switcher next --silent --linear --mod ctrl"),
--   { description = "Snappy Silent Switch" })

Could be mostly Any key!!

snappy-switcher next --linear will not work as intented if working with cli

-- Liquid Glass blur rules
 hl.layer_rule({ match = { namespace = "snappy-switcher" }, effect = "blur" })
 hl.layer_rule({ match = { namespace = "snappy-switcher" }, effect = "ignorealpha 0.01" })

Config Error Banner

You will see CONFIG ERROR banner is displayed if bind doesnt match with --mod

CLI MODE (No pop up or GUI)

With test flags you can use Snappy-Switcher via shell or terminal try --silent + --linear combo

Like this:- (Switching with Shell)

#try --silent alone to build mru and switch then break it with --linear (best for cli)
snappy-switcher next --silent
snappy-switcher next --silent --linear

Bind it

-- No GUI Switching with MRU
hl.bind("CTRL + S", hl.dsp.exec_cmd("snappy-switcher next --silent --mod CTRL"),
 { description = "Snappy Switcher CLI (MRU BUILDER)" })
-- Break MRU to move forward (then rebuild it)
hl.bind(
	"CTRL + W",
	hl.dsp.exec_cmd("snappy-switcher next --silent --linear --mod CTRL"),
   { description = "Snappy Switcher" }
 )

At this point just use Hyprlands binds (this are test flags)

Architecture

flowchart TB
    subgraph Client["Client Commands"]
        CMD["snappy-switcher next/prev"]
    end

    subgraph Daemon["Daemon Process"]
        SOCK["Unix Socket\n/run/user/$UID/snappy-switcher.sock"]

        subgraph Core["Core Logic"]
            HYP["hyprland.c\nIPC + Window Fetch"]
            CFG["config.c\nINI Parsing"]
            ICO["icons.c\nTheme Resolution"]
        end

        subgraph Render["Rendering"]
            RND["render.c\nCairo + Pango"]
            INP["input.c\nKeyboard + Dismiss"]
        end

        WL["Wayland\nLayer Shell"]
    end

    subgraph External["External"]
        HYP_IPC["Hyprland IPC"]
        DISP["Display Server"]
    end

    CMD -->|"send command"| SOCK
    SOCK --> HYP
    HYP <-->|"j/clients"| HYP_IPC
    CFG --> RND
    ICO --> RND
    HYP --> RND
    RND --> WL
    INP --> WL
    WL <--> DISP

    style SOCK fill:#89b4fa,stroke:#1e1e2e,color:#1e1e2e
    style HYP fill:#a6e3a1,stroke:#1e1e2e,color:#1e1e2e
    style RND fill:#cba6f7,stroke:#1e1e2e,color:#1e1e2e
    style WL fill:#f9e2af,stroke:#1e1e2e,color:#1e1e2e

Key Components

Full Architecture Documentation →

🛠️ Debugging & Development

Debug Script

The project includes a unified debug/profiler tool at ./scripts/snappy-debug.sh:

# Hammer with custom count
./scripts/snappy-debug.sh --hammer --count 1000

# Memcheck with custom config
./scripts/snappy-debug.sh --memcheck -c ./my-config.ini

Contributing

git clone https://github.com/OpalAayan/snappy-switcher.git
cd snappy-switcher
make

better do sudo make install enjoy it!!

Credits & Inspiration