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.

WinJitsu uses python-xlib and the RandR extension to enumerate connected monitors at runtime. Every grid-snapping action — N, S, E, W, the four corners, C, and F — applies relative to the monitor that contains the active window’s center point. This means the same hotkey always does the right thing regardless of which display your window is on.
WinJitsu requires the RandR extension. Xinerama-only setups are not supported. RandR is standard on virtually all X11 installations, so this is rarely a concern unless you are running a very unusual or embedded configuration.

​
How Monitor Detection Works

When the daemon handles an action, it calls get_screens() from screen.py. This function opens an Xlib display connection (shared and thread-safe across all daemon requests), checks for the RANDR extension, and queries xrandr_get_screen_resources() on the root window. For each output in the resource list, WinJitsu:
  1. Skips outputs that are not in the Connected state or have no active CRTC.
  2. Fetches the CRTC geometry (x, y, width, height) using xrandr_get_crtc_info().
  3. Identifies which output is primary via xrandr_get_output_primary().
The result is a tuple (primary_screen, [other_screens]) where each entry is a dictionary {"x": …, "y": …, "width": …, "height": …}. The primary display is placed first when iterating, so TD always cycles starting from primary.
WinJitsu queries screen resources using config_timestamp — not timestamp. Using timestamp causes BadMatch errors on some drivers and kernel versions. If you have encountered RandR crashes with other tools, WinJitsu’s approach avoids that class of bug.

​
Which Screen Is Used for Snapping

Before applying any grid position, WinJitsu calls find_screen_for_window(), which computes the window’s center point (window["X"] + window["WIDTH"] / 2, window["Y"] + window["HEIGHT"] / 2) and tests whether that point falls within any screen’s bounding rectangle.
  • If the center is inside exactly one screen, that screen is used.
  • If the center falls outside all screens (e.g. the window is mostly dragged off the edge of the desktop), WinJitsu falls back to the nearest screen by Euclidean distance from each screen’s center to the window’s center.
This means snapping always works predictably, even when a window straddles two monitors or is partially off-screen.

​
Moving a Window to the Next Monitor with TD

winjitsu TD (Toggle Display) cycles the active window forward through the list of connected monitors. The order is: primary first, then the remaining outputs in the order RandR reports them. When the window moves to the next screen:
  • Its relative offset from the origin of the current screen is preserved. For example, if the window is 100 px from the left edge of monitor A, it lands 100 px from the left edge of monitor B.
  • The offset is clamped to the new screen’s bounds so the window never partially leaves the visible area. The clamping formula used is: 
    target_x = max(target_screen["x"], min(target_x, target_screen["x"] + target_screen["width"] - window["WIDTH"]))
    An equivalent clamp is applied to the Y axis, keeping the window fully visible on the destination screen.
  • The window’s home state in the SQLite cache (~/.cache/winjitsu/state.db) is updated to reflect the new screen, so a subsequent U (restore) returns it to the correct position on the correct monitor.
If you only have one monitor connected, TD wraps back to the same screen — it is a no-op in practice.

​
Verifying Multi-Monitor Detection

1

Start the daemon

Open a terminal and start the WinJitsu daemon:
winjitsu --daemon
You should see output like winjitsu daemon starting (PID 12345). The daemon creates its socket at $XDG_RUNTIME_DIR/winjitsu/winjitsu.sock.
2

Open a window on your primary monitor

Open any application window — a terminal emulator, browser, or file manager — and make sure it is focused on your primary display.
3

Snap the window to the right half of the current screen

winjitsu E
The window should animate to the right half of your primary monitor. This confirms that WinJitsu has correctly identified the primary screen’s geometry.
4

Send the window to the next monitor

winjitsu TD
The window should animate across to your second display, preserving its vertical position and clamping horizontally to fit within the new screen’s bounds.
5

Snap the window on the new monitor

winjitsu W
The window should snap to the left half of the second monitor — not the left half of the entire combined desktop. This confirms that WinJitsu is computing positions relative to the screen the window is currently on.

​
Setup Requirements

  • python-xlib is a declared pip dependency of WinJitsu and is installed automatically when you install the package. If you are running from source, install it manually: 
    # Arch-based
sudo pacman -S python-xlib

# Debian/Ubuntu
sudo apt install python3-xlib

# Fedora
sudo dnf install python3-xlib
  • X11 session required. The RandR extension is part of the X11 protocol. WinJitsu does not support Wayland — even with XWayland active, the necessary window-management calls (xdotool windowsize, xdotool windowmove) do not function correctly under a Wayland compositor.
Bind TD to a key like Super+Shift+M so you can move any window to the next display in one keypress, then immediately use your directional bindings to place it exactly where you want on the new screen.

Build docs developers (and LLMs) love

Get started for freeTalk to us