bspwm-slidefx

Hyprland-style workspace slide animations for bspwm, powered by picom animation rules.

Click to watch demo

---

Overview

bspwm-slidefx wraps bspc desktop -f with picom animation hooks, tagging windows with X properties before the switch so picom can animate them sliding in and out. The switch works normally even when picom is not running. You just won't get the animation.

bspwm-slidefx-gestures is a companion daemon that maps 3-finger touchpad swipes to workspace switches using the same mechanism.

---

Requirements

Dependency	Required for	Install (Arch)
bspwm / bspc	workspace switching	pacman -S bspwm
picom	slide animation	yay -S picom
xprop	setting window properties	pacman -S xorg-xprop
xrandr	auto-detecting monitor width	pacman -S xorg-xrandr
libinput-tools	touchpad gestures	pacman -S libinput-tools

Note: The libinput-tools package is only required if you want 3-finger swipe support.

---

Installation

# 1. Clone the repository
git clone https://github.com/dhanush777x/bspwm-slidefx.git
cd bspwm-slidefx

# 2. Install to ~/.local/bin  (default)
make install

# or install system-wide
make install PREFIX=/usr/local

Make sure ~/.local/bin is in your PATH. If it is not, add this to your shell's rc file:

# ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

Uninstall

make uninstall

---

Picom Setup

Run once after installing:

bspwm-slidefx setup-picom

This will:

• Detect your picom config automatically (from the running process, standard locations, or your bspwmrc)
• Create the config file if it does not exist
• Insert a managed animation block - idempotent, safe to re-run
• Insert inside an existing rules: (...) section if one is present

Options:

# Specify a custom config path
bspwm-slidefx setup-picom --config ~/.config/picom/picom.conf

# Set slide distance explicitly (defaults to widest active monitor width)
bspwm-slidefx setup-picom --distance 2560

# Force rewrite even if the block is already up to date
bspwm-slidefx setup-picom --force

# Print the config path that would be used, without writing anything
bspwm-slidefx --print-picom-config-path

After setup, restart picom to pick up the new animation block.

---

Usage

Switching Workspaces

# By index
bspwm-slidefx -w 2

# By name
bspwm-slidefx -w web

# Relative
bspwm-slidefx -w next
bspwm-slidefx -w prev

sxhkd Bindings

Add to ~/.config/sxhkd/sxhkdrc:

# Switch by index
super + {1-9,0}
    bspwm-slidefx -w {1-9,10}

# Cycle workspaces
super + {comma,period}
    bspwm-slidefx -w {prev,next}

---

3-Finger Touchpad Swipe

Setup

1. Install libinput-tools:

# Arch
sudo pacman -S libinput-tools

# Debian / Ubuntu
sudo apt install libinput-tools

2. Add your user to the input group:

sudo usermod -aG input "$USER"

Then log out and back in for the group change to take effect.

3. Autostart the gesture daemon from your bspwmrc:

# ~/.config/bspwm/bspwmrc
bspwm-slidefx-gestures &

The daemon is self-guarded, calling it while already running exits silently, so reloading bspwmrc will not accumulate multiple instances.

Options

# More sensitive (fires on shorter swipes)
bspwm-slidefx-gestures --threshold 50 &

# Less sensitive (requires a longer deliberate swipe)
bspwm-slidefx-gestures --threshold 120 &

# Watch 4 fingers instead of 3
bspwm-slidefx-gestures --fingers 4 &

Option	Default	Description
--threshold PX	80	Accumulated horizontal pixels required to fire
--fingers N	3	Number of fingers to watch

How It Works

The daemon reads libinput debug-events line by line, tracking GESTURE_SWIPE_BEGIN, UPDATE, and END events. It accumulates the horizontal delta (dx) across each gesture and fires bspwm-slidefx -w next or bspwm-slidefx -w prev when the total exceeds the threshold. 2-finger scroll gestures are ignored. libinput reports them as a distinct event type.

---

Notes

• Animations are skipped gracefully when picom is not running, workspace switching still works
• The animation block excludes Polybar, eww-bar, and Dunst by default so bars don't slide

---

Troubleshooting

bspwm-slidefx: command not found

~/.local/bin is not in your PATH. Add this to your ~/.bashrc or ~/.zshrc:

export PATH="$HOME/.local/bin:$PATH"

Then reload your shell (source ~/.bashrc) or open a new terminal. You can verify with:

which bspwm-slidefx

Commands work in terminal but not from sxhkd / bspwmrc

sxhkd and bspwmrc do not source your shell rc file, so ~/.local/bin may not be in the PATH they see. Fix this by using the full path in your configs:

# ~/.config/sxhkd/sxhkdrc
super + {1-9,0}
    /home/yourusername/.local/bin/bspwm-slidefx -w {1-9,10}

super + {comma,period}
    /home/yourusername/.local/bin/bspwm-slidefx -w {prev,next}

# ~/.config/bspwm/bspwmrc
/home/yourusername/.local/bin/bspwm-slidefx-gestures &

Or export PATH at the top of your bspwmrc:

export PATH="$HOME/.local/bin:$PATH"

Animations not playing

1. Confirm picom is running: pgrep -x picom
2. Re-run setup and restart picom:

   bspwm-slidefx setup-picom --force
   # then restart picom

Gestures not working - missing required commands: libinput

The libinput CLI is in libinput-tools, not the base libinput library package:

# Arch
sudo pacman -S libinput-tools

# Debian / Ubuntu
sudo apt install libinput-tools

Gestures not working - permission denied on /dev/input

You are not in the input group:

sudo usermod -aG input "$USER"
# log out and back in
groups | grep input   # verify

Gesture daemon exits immediately

Check if another instance is already running:

cat /tmp/bspwm-slidefx-gestures.pid
ps -p $(cat /tmp/bspwm-slidefx-gestures.pid)

If the PID is stale (process not running), remove the file and try again:

rm -f /tmp/bspwm-slidefx-gestures.pid
bspwm-slidefx-gestures &

---

License

MIT License — do whatever you want with it, just don't remove the attribution.

Copyright (c) 2025 Dhanush S M

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

Your bspwm deserves smooth animations too. Hope this makes your desktop feel as good as it looks. Enjoy the slides ✨