# My Pekwm Setup
I run **pekwm** on **GhostBSD** with **Xorg** as my daily window manager.
It’s light, fast, and highly configurable — exactly what I want for a simple yet powerful desktop environment.
My workflow is mostly **keyboard-driven**, with custom keybindings for navigation, window management, and launching applications.
I also rely on pekwm’s **grouping feature** to keep things organized: all my PDFs open in a single tabbed frame, and I can launch multiple terminal windows grouped together for easier handling.
On top of that, I’ve added a few helper scripts, a custom menu generator, and some small tweaks for hardware control like volume, brightness, and touchscreen toggling.
I've added a simple system that save and restore your pekwm session. So you retreive your environment exactly where it was before shutdown.
The result is a **minimalist, efficient, and responsive environment** that fits my workflow perfectly, without unnecessary overhead.
# Theme
My theme is a slightly modified version of **Minimalst** by [Myugan](https://www.gnome-look.org/p/1137146).
My main modificaitons concern the sizes and the slight modificaitons of border's colors.
Thus a window having the focus is white, the orhers are lighblue
# Config
I mostly use the default configuration and have not made major changes.
# Autoproperties
Since I often open a large number of PDFs, I make use of the **grouping feature** in pekwm.
This allows me to collect similar windows into tabs, and I can even define how many tabs a group can hold.
Here is the rule I use for **Atril** (PDF reader):
Property = "^atril,^Atril" {
ApplyOn = "New"
Group = "pdf" {
Size = "15"
FocusedFirst = "True"
Raise = "True"
}
}
I also use a similar rule for **Alacritty** terminals that I launch with a special class (`grouped`):
Property = "^grouped,^grouped" {
ApplyOn = "New"
Group = "grouped" {
Size = "15"
FocusedFirst = "True"
Raise = "True"
}
ClientGeometry = "1280x640+50+200"
}
Such grouped Alacritty windows are created with:
alacritty --class grouped
I have a specific config for my pseudo lockscreen made with xterm.
It display in full screen and without border an xterm window displaying battery info.
Property = "xterm,Bigscreen" {
# ApplyOn = "Start New"
ApplyOn = "New"
Border = "False"; Titlebar = "False"
Sticky = "True"
Fullscreen = "True"
}
To use this autoproperties, I lauch my app via the following command:
xterm -fa Monospace -fs 26 -bg black -fg black -title mybattery -class Bigscreen -e $HOME/.pekwm/scripts/xterm_mybattery.sh
The keyword here is the "-class BigScreen" which tels to pekwm to make it fullscreen and without borders, title, ...
A good way to defined what must be the Property value, you can use the following command:
xprop WM_CLASS | sed 's/.*"\(.*\)", "\(.*\)".*/ "\1,\2" /g'
# Vars
I define a few environment variables to simplify launching applications:
$BROWSER="firefox"
$EDITOR="alacritty -e nvim"
$FILEMANAGER="spacefm"
$EMAILS="thunderbird"
$TERM="alacritty --class grouped"
For keyboard-driven window movement and resizing, I also set:
$MOVERESIZE_INCREMENT="15"
# Keys
## Pekwm Keybindings Documentation
This section explains my **`keys`** configuration for **pekwm**, a lightweight and flexible window manager.
It details the key bindings, actions, and custom scripts referenced in my setup.
### 1. Includes
At the top of the config, I include common variables and modular keybinding files:
INCLUDE = "vars"
INCLUDE = "$_PEKWM_ETC_PATH/keys_inputdialog"
INCLUDE = "$_PEKWM_ETC_PATH/keys_menu"
INCLUDE = "$_PEKWM_ETC_PATH/keys_moveresize"
* **vars** – user-defined environment variables (`$TERM`, `$EDITOR`, `$BROWSER`, etc.).
* **keys_inputdialog**, **keys_menu**, **keys_moveresize** – modular sets of bindings for input dialogs, menus, and resizing.
### 2. Global Bindings
These are the most frequently used shortcuts available everywhere.
#### Frame Navigation
* **Alt+Tab** – Next frame (raise temporarily).
* **Alt+Shift+Tab** – Previous frame (raise temporarily).
* **Alt+Ctrl+Tab** – Next frame (raise permanently).
* **Alt+Ctrl+Shift+Tab** – Previous frame (raise permanently).
* **Super+Tab / Super+Shift+Tab** – Cycle through clients within a frame.
* **Super+Ctrl+Left/Right** – Move client left/right in frame.
* **Super+Arrow keys** – Focus neighboring windows (directional).
#### Workspace Navigation
* **Ctrl+Alt+Arrow** – Switch workspace in the given direction.
* **Ctrl+Super+Shift+Left/Right** – Jump to next/previous workspace (wrap).
* **Super+1..9** – Switch directly to workspace 1–9.
* **Ctrl+Alt+Shift+Arrow** – Send window to another workspace and follow it.
* **Super+Shift+1..9** – Send window to workspace 1–9.
#### Window Management
* **Super+M** – Toggle maximized.
* **Super+F** – Toggle fullscreen.
* **Super+Shift+U** – Resize to 50% × 50%.
* **Super+Shift+Z** – Resize to 50% × 100%.
* **Super+Shift+H** – Resize to 100% × 50%.
* **Super+Return** – Interactive move/resize.
* **Super+Shift+Arrow** – Snap window to screen edge.
* **Super+Q** – Close window.
* **Super+S** – Shade window (roll up).
* **Super+I** – Iconify (minimize).
#### Marking / Tagging
* **Super+Z** – Toggle window mark.
* **Super+A** – Attach marked windows into one frame.
* **Super+T** – Toggle tagged state.
#### Menus
* **Super+Space** – Show root menu.
* **Super+W** – Show window menu.
* **Super+L** – Show workspace navigation menu.
* **Super+C** – Show client menu.
* **Super+Shift+I** – Show icon menu.
* **Super+X** – Hide all menus.
#### External Commands
* **Print** – Run screenshot script.
* **Super+E** – Launch terminal.
#### Pekwm Control
* **Ctrl+Alt+Delete** – Restart pekwm.
* **Super+V** – Show search dialog.
* **Super+H** – Toggle harbour (dock/panel).
### 3. Chains
Chains are shortcuts with a **prefix key** followed by a second key.
* **Ctrl+Super+C** – Move windows to corners/edges.
* **Ctrl+Super+M** – Open menus (root, window, icon, goto, etc.).
* **Ctrl+Super+T** – Grouping & tagging.
* **Ctrl+Super+D** – Toggle borders/titlebars.
* **Ctrl+Super+W** – Window management (resize, maximize, geometry presets).
* **Ctrl+Super+F** – Frame navigation (cycle, move clients, focus).
* **Ctrl+Super+S** – Full workspace management.
* **Ctrl+Super+E** – Launch external apps (`$TERM`, `$BROWSER`, `$EMAILS`, `$FILEMANAGER`).
* **Ctrl+Super+H** – Quick-open config files in `$EDITOR`.
* **Ctrl+Super+P** – Reload, restart, exit pekwm, or show command dialog.
### 4. Custom Additions
I also added some personal bindings for hardware control and scripts:
* **F1** – Toggle audio mute.
* **F2/F3** – Volume down/up by 5%.
* **F5/F6** – Screen brightness down/up.
* **Ctrl+Alt+T** – Toggle touchscreen.
* **Super+B** – a kind of lock screen which show battery info in xterm.
* **Super+D** – Run `displayVaico.sh` my panel (cfr vaico project).
### 5. Notes
* `$TERM`, `$EDITOR`, `$BROWSER`, `$EMAILS`, `$FILEMANAGER` are defined in **vars**.
* Helper scripts are in `$_PEKWM_CONFIG_PATH/scripts/` (e.g. `takeScreenShot.sh`, `toggle_touchscreen.sh`).
* The **Harbour** is pekwm’s dock-like bar, which can be hidden or shown.
# Menu
I use a dedicated script to generate my **pekwm menu** from installed XDG `.desktop` entries.
It automatically categorizes applications, adds system utilities, and builds a structured `~/.pekwm/menu` file ready to use.
For details, see **README_createMenu.md**.
# Save and restore pekwm sessions
Thanks to pekwm_ctrl we list all opened windows. We check their associated PID and analyse their window's title.
This is consolidated in a small Python script called saveSassesion.py.
This information is saved into ~/.local/db/pekwm-session.
In order to save this information, small halt.sh, reboot.sh and logout.sh scripts have been made. They also store logging information in ~/.pekwm/pekwm_scripts.log.
Once you restart you pekwm session, the "start" script is automatically triggered by pekwm. So, this script initiate restoreSession.py. This python script look at ~/.local/db/pekwm-session and decide which applications must be restarted.
