swtchr is both an executable binary that can be run, and a library that can be used in Rust programs.

Installing `swtchr` `swtchrd` executables

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install swtchr

It will make swtchr swtchrd commands available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall swtchr uninstalls.

Adding `swtchr` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add swtchr

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

swtchr = "0.1.3"

The swtchr library will be automatically available globally.

Back to the crate overview.

Readme

swtchr

A screenshot of the swtchr window switcher over a Sway desktop

A pretty Gnome-style window switcher for the Sway window manager.

Out of the box, you can use <Super>Tab and <Super><Shift>Tab to page forward and backward through a list of windows ordered from most to least recently accessed.

Installing

You can find prebuilt binaries on the releases page, or you can build from source.

To build from source, you'll need to install these system dependencies:

Then install Rust and run this command (you do not need to clone the repo):

cargo install swtchr

This will install the swtchr and swtchrd binaries to ~/.cargo/bin/.

Getting started

To get started, drop these commands into your Sway config, which is usually located at ~/.config/sway/config. Substitute whatever path you installed the swtchr and swtchrd binaries to.

# Start the swtchr daemon.
exec_always ~/.cargo/bin/swtchrd

# Set up keybinds to open the window switcher.
bindsym $mod+Tab mode swtchr; exec ~/.cargo/bin/swtchr
bindsym $mod+Shift+Tab mode swtchr; exec ~/.cargo/bin/swtchr

# This is important! More information below.
mode swtchr bindsym Backspace mode default

See Configuring swtchr to customize the behavior and keybindings.

See Styling swtchr to to customize the appearance.

See Sway keybinds to understand what's going on with the mode swtchr part.

See Using systemd to start the swtchr daemon via a systemd service instead of via your Sway config.

See Recipes for some examples of different ways you can configure swtchr.

Configuring swtchr

You can configure the behavior and keybindings for swtchr in ~/.config/swtchr/swtchr.toml. An example config file with sensible defaults will be generated there the first time you start the swtchr daemon.

The comments in the example config file document what each option does. You can find it at src/swtchr.toml.

swtchr will look for the swtchr.toml file in these places:

$XDG_CONFIG_HOME/swtchr/swtchr.toml
~/.config/swtchr/swtchr.toml

Styling swtchr

You can customize the styling of the window switcher using GTK CSS. Just drop a CSS file here:

~/.config/swtchr/style.css

You can look at the default stylesheet src/style.css as an example.

Additionally, you can open the interactive GTK debugger to inspect objects, see their CSS classes, and apply CSS styles live:

env GTK_DEBUG=interactive swtchrd

swtchr will look for the style.css file in these places:

$XDG_CONFIG_HOME/swtchr/style.css
~/.config/swtchr/style.css

Sway keybinds

You need to configure keybinds in your Sway config to open the window switcher. All other swtchr keybinds are configured in the swtchr config file.

Let's break down the Sway keybinds we set up in Getting started:

bindsym $mod+Tab mode swtchr; exec ~/.cargo/bin/swtchr
bindsym $mod+Shift+Tab mode swtchr; exec ~/.cargo/bin/swtchr

We're using <Super>Tab both to open the window switcher and to cycle through windows once it's open. To prevent Sway from consuming those keypresses once the window switcher is open, we need to change the Sway binding mode. swtchr will automatically change your binding mode back to default when the window switcher closes.

mod swtchr bindsym Backspace mode default

Sway only allows you to change the binding mode if you've configured a keybind to escape back to the default mode, so you'll need this line as well. You may need to use this keybind if the swtchr daemon crashes before it's able to switch back to the default mode.

Using systemd

Rather than start the swtchr daemon via an exec_always command in your Sway config, you may want to use a systemd service instead. This enables restart-on-failure behavior and makes checking the logs easier.

There is an example systemd unit file provided in etc/swtchrd.service. Update the ExecStart= line to match the path you installed the swtchrd binary to, and then drop it here:

~/.config/systemd/user/swtchrd.service

From there, you can run this command to start the swtchr daemon and configure it autostart when you log into a Sway session:

systemctl --user enable --now swtchrd.service

If your distro doesn't package Sway with a sway-session.target, check out these docs on how to roll your own.

Recipes

Out of the box, swtchr only switches focus to the selected window when you release <Super>Tab / <Super><Shift>Tab. You can optionally enable "peeking" to switch window focus immediately as you cycle through windows in the switcher.

# swtchr.toml

[keymap]

#next = "<Super>Tab"
peek_next = "<Super>Tab"

#prev = "<Super><Shift>Tab"
peek_prev = "<Super><Shift>Tab"

Instead of switching window focus and closing the window switcher immediately when you release <Super>Tab / <Super><Shift>Tab, you can configure swtchr with separate keybinds to a) switch to the selected window or b) dismiss the window switcher.

# swtchr.toml

dismiss_on_release = false
select_on_release = false

[keymap]

dismiss = "Escape"
select = "Return"

Installing swtchr swtchrd executables

Adding swtchr library as a dependency

Installing `swtchr` `swtchrd` executables

Adding `swtchr` library as a dependency