Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Evilchuck666/WinJitsu/llms.txt

Use this file to discover all available pages before exploring further.

Most WinJitsu issues fall into three categories: missing system dependencies (xdotool or python-xlib), a daemon that is not running or has a stale PID file, or stale cache state in the SQLite database at ~/.cache/winjitsu/state.db. Work through the items below in order — the first two cover the vast majority of problems.

​
Common Problems

This message is printed to stderr when winjitsu <ACTION> cannot connect to the daemon socket at $XDG_RUNTIME_DIR/winjitsu/winjitsu.sock. The daemon either was never started, crashed, or left a stale socket.Start the daemon:
winjitsu --daemon
You should see winjitsu daemon starting (PID <n>). After that, actions will work immediately.If the daemon reports it is already running but actions still fail, there is likely a stale PID file from a previous session (e.g. after a hard reboot). The client will print:
No daemon running (stale PID file).
Use the reload command to clean it up and restart:
winjitsu --reload-daemon
If --reload-daemon itself errors, you can clean up manually:
# Find and remove the stale PID file
rm -f "$XDG_RUNTIME_DIR/winjitsu/winjitsu.pid"

# Remove the stale socket if it exists
rm -f "$XDG_RUNTIME_DIR/winjitsu/winjitsu.sock"

# Start fresh
winjitsu --daemon
WinJitsu uses xdotool to query the active window ID, geometry, and WM class, and to send windowsize / windowmove commands during animation. This error means xdotool is not on your PATH.Install xdotool for your distribution:
# Arch-based (Arch Linux, EndeavourOS, Manjaro)
sudo pacman -S xdotool

# Debian-based (Debian, Ubuntu, Linux Mint)
sudo apt install xdotool

# Fedora-based (Fedora, CentOS Stream)
sudo dnf install xdotool
After installing, verify it is accessible:
xdotool getactivewindow
This should print the numeric window ID of your focused window. If it prints an error instead, confirm that /usr/bin/xdotool exists and that your PATH includes /usr/bin.
WinJitsu raises this error inside get_screens() when python-xlib cannot find the RANDR extension on the running X server. There are two causes: python-xlib is not installed, or you are not running an X11 session.python-xlib is installed automatically as a pip dependency when you install WinJitsu. If you are running from source or it was somehow removed, install it manually:
# Arch-based
sudo pacman -S python-xlib

# Debian-based
sudo apt install python3-xlib

# Fedora-based
sudo dnf install python3-xlib
Confirm you are on X11, not Wayland. Check the session type:
echo $XDG_SESSION_TYPE
If this prints wayland, WinJitsu will not function — see the Wayland item below. Log out and choose an X11/Xorg session from your display manager.If you are already on X11 and the error persists, check that the RandR extension is loaded in your X server:
xrandr --version
A working RandR installation prints the version. If xrandr is missing, install the xrandr package for your distribution.
The U (Unscreen/Restore) action reads the window’s home state from the SQLite cache at ~/.cache/winjitsu/state.db. If no state has been saved for the active window, WinJitsu logs:
WARN: no cached state for this window
If the cache contains stale geometry — for example because the window was resized externally, the monitor layout changed, or a previous WinJitsu session wrote bad data — the window will jump to an incorrect position.Clear the cache and re-snap:
winjitsu CC
This deletes all rows from the windows table in the state database. The next time you snap a window with any direction action, WinJitsu records a fresh home state from the window’s current position.After clearing, snap the window to any position (e.g. winjitsu N) and then try winjitsu U — it should restore correctly.
When you run winjitsu --reload-daemon, WinJitsu sends SIGTERM to the running daemon and polls every 100 ms for up to 5 seconds waiting for the process to exit. If the daemon hangs (e.g. due to a blocked socket operation or deadlock), the reload times out and prints:
Daemon did not stop within 5 seconds.
Manually terminate the old daemon and restart:
# Read the PID from the file
OLD_PID=$(cat "$XDG_RUNTIME_DIR/winjitsu/winjitsu.pid")

# Force-kill it
kill -9 "$OLD_PID"

# Remove the stale runtime files
rm -f "$XDG_RUNTIME_DIR/winjitsu/winjitsu.pid"
rm -f "$XDG_RUNTIME_DIR/winjitsu/winjitsu.sock"

# Start a fresh daemon
winjitsu --daemon
If you receive Permission denied sending SIGTERM. instead of the timeout message, WinJitsu could not signal the daemon process (the process exists but is owned by a different user). Confirm you are running as the same user that started the daemon.
The animation runs for steps frames using a smoothstep easing curve. The default is 25 steps. Fewer steps make the animation faster but choppier; more steps make it smoother but slower.Tune steps for this session only:
# Start the daemon with snappier animation
winjitsu --daemon --steps 10

# Start the daemon with ultra-smooth animation
winjitsu --daemon --steps 40
Persist the setting to your config file so you do not have to pass the flag every time:
winjitsu --write-config --steps 15
This writes steps = 15 under the [animation] section of ~/.config/winjitsu/config.ini. Future daemon starts will pick it up automatically.The --padding option also affects the visual result for F and TF — set it to a small pixel value (e.g. --padding 8) if you want a gap between the window and the screen edge when fullscreening.
WinJitsu is an X11-only tool. It relies on xdotool for window manipulation and python-xlib with RandR for screen detection. Neither works correctly under a Wayland compositor:
  • xdotool getactivewindow returns nothing or errors under Wayland.
  • XWayland provides an X11 compatibility layer for individual apps, but the window manager itself is Wayland-native and does not expose X11 window management APIs.
Solution: Log out and select an Xorg/X11 session from your display manager (e.g. “GNOME on Xorg”, “Plasma (X11)”, or a bare i3/Openbox session). WinJitsu will work immediately in an X11 session.If your distribution no longer ships an X11 session option, WinJitsu is not compatible with your setup at this time.
WinJitsu looks for its config file at $XDG_CONFIG_HOME/winjitsu/config.ini, which defaults to ~/.config/winjitsu/config.ini when $XDG_CONFIG_HOME is not set.Verify the active config path and current values:
winjitsu --see-config
This prints the resolved path and whether the file exists, followed by the effective values for steps, padding, and delay_ms. If it says not found — using defaults, the file does not exist at the expected path.Create the config file with current defaults:
winjitsu --write-config
Common mistakes:
  • $XDG_CONFIG_HOME is set to a non-standard path in your shell profile — run echo $XDG_CONFIG_HOME to check.
  • The INI file has a syntax error (missing =, wrong section header, etc.). The file must follow standard INI format: 
    [animation]
steps = 20

[display]
padding = 5

[daemon]
delay_ms = 200
  • You passed --read-config PATH with a wrong path. Use winjitsu --see-config to confirm which file is being read.

​
Useful Diagnostic Commands

The following commands help you quickly inspect WinJitsu’s state without digging through logs or files manually.
CommandWhat it tells you
winjitsu --see-configActive config file path, whether it exists, and current values
winjitsu --reload-daemonGracefully restarts the daemon (stops old, starts new)
winjitsu CCClears all rows from the window state cache in the SQLite DB
echo $XDG_RUNTIME_DIRConfirms the runtime directory path used for socket and PID file
ls $XDG_RUNTIME_DIR/winjitsu/Verifies that winjitsu.sock and winjitsu.pid are present
If your problem is not listed here, please open an issue on the WinJitsu GitHub repository. Include the output of winjitsu --see-config, your distribution name and version, and a description of what you expected versus what happened.

Build docs developers (and LLMs) love

Get started for freeTalk to us