Introduction

A YAD (GTK) based graphical configuration manager for picom-ftlabs and other similar forks, focused on animations, blur, shadows, fading, and window opacity. This tool edits an existing picom configuration file using an external parser (sedscripts) and provides a modular notebook-style GUI.

Before You Get In

• This project is NOT an AUR package (yet)
• It is intended to be built from source
• Some dependencies must be built manually first (sedscripts is a required dependency)
• This GUI is designed specifically for picom-ftlabs and other similar animation focused picom forks.
• This is not a QT application. It is GTK based and you would not be able to get a good UI from QT system.

Dependencies

The following must be installed before building or running picom-gui:

Warning

If the dependencies are not met, the gui would not be able to start, or it may destroy your picom configuration. It is always recommended to keep a backup of your picom configuration as picom.backup.ref somewhere in a safe location.

Required

• picom-ftlabs-git (fork of picom with animation support, or any other similar forks which has inbuilt animation support, blur options and similar compositing features that are in picom-ftlabs-git)
• yad (GTK dialog toolkit, this tool provides the graphical user interface for picom)
• sed (The file manipulation command line tool)
• bash
• bc (The terminal calculator)
• sedscripts (The Config Parser specifically built for simplifying usage)

sedscripts (mandatory)

sedscripts is not available in official repos or AUR and must be built directly from my repository. Repo : https://github.com/rdbhvr-001/sedscripts.git

Sedscripts is a powerful tool which gives you leverage to edit config files without even opening them. You can check if the key exists in the config file, extract the value and even edit it.

Install Dependencies

You must build and install dependencies in the correct order. Never fail to install sedscripts. sedscripts is the processor for this entire gui.

1) Build and install sedscripts

git clone https://github.com/rdbhvr-001/sedscripts.git
cd sedscripts
makepkg -si

Verify Installation

which sedscripts
#output : /usr/bin/sedscripts

2) Build and Install picom-ftlabs-git

Using an AUR helper, you can directly install picom-ftlabs-git, which is a dependency for picom-gui. You can also alternatively install any picom fork which supports the features of picom-ftlabs-git. But I would recommend you to use picom-ftlabs-git. I have not tested it with other picom forks but I am pretty sure that it will support other similar forks too.

paru(or)yay -S picom-ftlabs-git #or any other similar forks

3) Build and Install picom-gui

git clone https://github.com/rdbhvr-001/picom-gui.git
cd picom-gui
makepkg -si

Notes

• sedscripts provides safe key–value parsing and replacement utilities.
• picom-gui will not run without sedscripts installed.
• If sedscripts is updated, picom-gui does not need to be rebuilt.

Simple Usage : picom-gui

Note

It is recommended to have your picom.conf file at this location : ~/.config/bspwm/bspwm.d/picom.conf else, you would have to specify the configuration path every time.

You can either symlink actual picom.conf at that specified location, or run :

picom-gui <config-path> <plug value Z+ > # Same order. if you define a plug value, then 
# you should also define a config path.

Features

• GTK (YAD) based graphical interface for configuring picom
• Designed specifically for picom-ftlabs
• Modular notebook-style UI with separate configuration tabs
• General compositor settings (backend, vsync, damage, logging)
• Shadow configuration (enable/disable, radius, opacity, offsets, color)
• Blur configuration with support for xrender and GL backends
• Fading controls (fade-in, fade-out, delta, ARGB handling)
• Animation controls (stiffness, dampening, clamping, window mass)
• Per-event animation selection (open, unmap, transient windows)
• Window appearance controls (corner radius, opacity, dimming)
• Percentage-based UI values with automatic picom-scale conversion
• Safe and precise config editing using sedscripts (old → new replacement)
• No hardcoded paths; configurable target config file
• Supports embedding via YAD plug for integration into larger GUIs
• Does not overwrite config blindly; preserves structure and formatting using sedscripts
• Works with manually built picom forks and custom setups
• Repo-first workflow (no AUR required).

Note

If you are going to specify exclude rules or other rules in picom, you would have to manually do in your config file. picom-gui does not support picom rules and window exclude options. It does not also modify any of those options if already present in your config. Planning to add those features in future updates.

Command Usage

The picom-gui command launches a graphical configuration editor for picom.

Syntax

picom-gui [CONFIG_FILE] [YAD_PLUG_ID]

Arguments

CONFIG_FILE : Optional if you are using bspwm.d directory tree.

The default path for all picom config files is based on modular bspwm configurations which uses a special bspwm.d directory to store config and bspwm related files. Located @ : ~/.config/bspwm/bspwm.d/picom.conf

Tip

Method 1 If you are not using a modular model of bspwm, or if you are using other window managers or desktop environments, you can either create the directory mkdir -p ~/.config/bspwm/bspwm.d and symlink your actual picom.conf file to that location ln -s <path of your actual picom.conf> ~/.config/bspwm/bspwm.d/picom.conf

Method 2 (recommended) Else, you can specify the path of your picom.conf (immediately after picom-gui) each time like picom-gui ~/.config/picom/picom.conf and alias the picom-gui to that path

YAD_PLUG_ID : Optional.

Numeric YAD plug identifier used to embed picom-gui into an existing YAD notebook window. Default: 23483

Warning

It is best to copy this picom.conf file to where ever you want and then use this file to load picom-gui because picom-gui searches for default options (most of the options are preincluded in this config) to load the saved values. When any key is not present, it may throw errors. To ensure that your picom configuration has all the keys, you are required to copy picom-gui's picom.conf file to the path from which you are going to load picom-gui.

Required for Loading Values

# Backup the config
mv ~/.config/bspwm/bspwm.d/picom.conf ~/.config/bspwm/bspwm.d/picom.backup.ref
# Or use mv <your picom.conf path> <your picom.conf path>.ref

cp -r picom.conf ~/.config/bspwm/bspwm.d/picom.conf
# Or use cp -r picom.conf <the path from which you load picom.conf>

Examples

Launch picom-gui using the default configuration file:

picom-gui

Edit a custom picom configuration file:

  picom-gui ~/.config/picom/picom.conf

Embed picom-gui into an existing YAD notebook using a custom plug ID:

  picom-gui ~/.config/picom/picom.conf 77777

The Showcase

1) General Settings

2) Shadows

3) Fading

4) Animations

5) Blur Background

6) Transparency

Contributions are Welcomed

Feel free to create a pull request or open up an issue about adding features and fixing issues.