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.

This guide walks you from a fresh WinJitsu installation to snapping your first window. The whole process takes less than two minutes: start the daemon, confirm it is healthy, then fire a couple of action commands to see the animations in action. Once you are comfortable with the basics, the final step shows how to bind WinJitsu actions to keyboard shortcuts so you never have to touch the terminal again.
WinJitsu debounces rapid keypresses — if you trigger the same action several times in quick succession (e.g. from key-repeat), only the last action in the burst fires. The default debounce window is 250 ms and is configurable with --delay-ms when starting the daemon.
1

Start the daemon

WinJitsu actions are sent to a background daemon over a Unix socket. Start it once per session (or add it to your session autostart):
winjitsu --daemon
The process forks immediately into the background and writes its PID to a file so it can be found and stopped later. You will see a brief startup message in the terminal:
winjitsu daemon starting (PID 12345)
To restart a running daemon (e.g. after changing config values), use:
winjitsu --reload-daemon
2

Check your configuration

Inspect the active configuration file path and all resolved values:
winjitsu --see-config
WinJitsu prints the location of the active config file and all resolved values:
config file : /home/alice/.config/winjitsu/config.ini  (not found — using defaults)
steps       : 25
padding     : 0
delay_ms    : 250
If you then run an action command without a running daemon, WinJitsu prints an error and exits cleanly:
Error: WinJitsu daemon is not running. Start it with: winjitsu --daemon
3

Snap a window

Open any application window and make sure it is the focused window. Then run:
winjitsu N
The window glides to the top half of your screen. Try a few more positions:
winjitsu E    # right half
winjitsu SW   # bottom-left quarter
winjitsu C    # centered (keeps current size)
winjitsu F    # fullscreen (covers the entire monitor)
Each command is sent to the daemon over the Unix socket. The daemon debounces the request, then steps the window geometry from its current position to the target over 25 animation frames (by default).
4

Restore the window

WinJitsu caches the window’s original geometry before every snap or fullscreen operation. To restore it:
winjitsu U
The window animates back to the size and position it occupied before the last F or grid-snap action. If you want to toggle between fullscreen and restored without separate commands, use:
winjitsu TF
5

Bind a hotkey

For everyday use, bind WinJitsu actions to keyboard shortcuts in your window manager. Here is a minimal i3 example:
bindsym $mod+Up    exec winjitsu N
bindsym $mod+Down  exec winjitsu S
bindsym $mod+Right exec winjitsu E
bindsym $mod+Left  exec winjitsu W
bindsym $mod+f     exec winjitsu F
bindsym $mod+u     exec winjitsu U
Because the daemon is already running, each exec winjitsu [ACTION] call returns in milliseconds — the CLI simply writes the action to the socket and exits. For GNOME, KDE, and other desktop environments, see Hotkey Binding for full step-by-step examples.

​
Explore Further

Actions Reference

Complete reference for all 14 action codes — grid positions, fullscreen, multi-monitor, and cache management.

Hotkey Binding

Step-by-step instructions for binding WinJitsu actions in i3, GNOME, KDE, and more.

Build docs developers (and LLMs) love

Get started for freeTalk to us