WinJitsu is a lightweight, animated window management tool for Linux X11 desktops. Instead of the jarring instant-teleport behaviour of most tiling helpers, WinJitsu glides your active window to any grid position — half-screen, quarter-screen, center, or fullscreen — with a smooth, configurable animation. It is designed for power users who want keyboard-driven window placement without switching to a full tiling window manager, and it works with any X11 session: i3, Openbox, GNOME on X, KDE on X, and more.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.
Key Features
Smooth Animations
Windows glide to their new positions over a configurable number of steps rather than snapping instantly, giving your workflow a polished, fluid feel.
Grid Snapping
Snap to eight cardinal and diagonal positions (N, S, E, W, NE, NW, SE, SW) plus a centered layout — all with a single keypress.
Multi-Monitor Support
Move the active window to the next connected display with the
TD action. WinJitsu uses RandR via python-xlib to detect all connected monitors automatically.Fullscreen Toggle
The
F action covers the entire monitor with configurable pixel padding. U restores the window to exactly where it was before, and TF toggles between the two states.Background Daemon
Run WinJitsu as a persistent daemon (
winjitsu --daemon) so hotkey responses are instant and repeated keypresses are collapsed into a single clean action.Config File
Persist your preferences in
~/.config/winjitsu/config.ini (XDG-compliant). Create it with winjitsu --write-config and inspect it at any time with winjitsu --see-config.CLI Overrides
Every config value — animation steps, fullscreen padding, debounce delay — can be overridden directly on the command line when starting the daemon, no file editing required.
SQLite State Cache
WinJitsu caches each window’s original geometry so it can be restored precisely after a fullscreen or snap operation. The cache can be cleared at any time with
winjitsu CC.How It Works
WinJitsu uses a client–daemon architecture over a Unix socket. When you run a command such aswinjitsu N, the CLI acts as a thin client: it serialises the action code and writes it to the socket. The daemon — already running in the background — receives the message, waits out its configured debounce delay (default 250 ms) to collapse any rapid-fire duplicates, then drives the animation by issuing a rapid sequence of xdotool windowmove and xdotool windowsize calls, stepping the window geometry from its current position to the target position over the configured number of animation steps. Screen geometry is resolved at runtime via python-xlib and the RandR extension, so multi-monitor layouts are always up to date.
WinJitsu is an X11-only tool. It relies on
xdotool and the X11 RandR extension and will not work on a Wayland session. If you are running GNOME or KDE under Wayland, you must either switch to an X11 session or use a Wayland-native alternative.System Requirements
Before installing WinJitsu, make sure the following are present on your system:| Requirement | Minimum version | Notes |
|---|---|---|
| Python | 3.10+ | Required for modern match/case and tomllib |
xdotool | Any recent version | Used to move and resize windows |
python-xlib | Any recent version | Used for RandR monitor detection |
| X11 display server | Any | Wayland is not supported |
Next Steps
Installation
Install WinJitsu via the AUR, build a wheel from source, or install directly with pip.
Quickstart
Start the daemon and snap your first window in under two minutes.