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 is designed to be driven by hotkeys. Because it runs as a background daemon, the winjitsu <ACTION> client command connects to a Unix socket at $XDG_RUNTIME_DIR/winjitsu/winjitsu.sock and returns nearly instantly — making it ideal for hotkey bindings without any perceptible lag. You bind each action once, start the daemon at login, and WinJitsu stays invisible until you need it.
Start the daemon at login before configuring hotkeys. Every winjitsu <ACTION> call silently fails if the daemon is not running. Add winjitsu --daemon to your session autostart so it is always ready when you press a key.
Action-to-Key Mapping Reference
The table below is a suggested starting layout. Use it as-is or adapt it to your preferences — any key combination your window manager accepts will work with any WinJitsu action.
| Action | Suggested Key | Description |
|---|
N | Super + Up | Snap to top half of the current monitor |
S | Super + Down | Snap to bottom half of the current monitor |
E | Super + Right | Snap to right half of the current monitor |
W | Super + Left | Snap to left half of the current monitor |
NE | Super + Shift + Up | Snap to top-right quarter |
NW | Super + Shift + Left | Snap to top-left quarter |
SE | Super + Shift + Right | Snap to bottom-right quarter |
SW | Super + Shift + Down | Snap to bottom-left quarter |
C | Super + C | Center the window (preserves current size) |
F | Super + F | Fullscreen (covers the entire monitor) |
U | Super + U | Restore window to its original position |
TF | Super + T | Toggle fullscreen / restore home position |
TD | Super + Shift + M | Move window to the next monitor |
Configuration by Window Manager
i3 / i3-gaps
GNOME
KDE Plasma
Openbox
i3 and i3-gaps support bindsym and exec_always natively, making WinJitsu a natural fit. Add the following block to your ~/.config/i3/config (or ~/.i3/config).The exec_always --no-startup-id winjitsu --daemon line restarts the daemon every time i3 reloads its config, so it survives $mod+Shift+r without you having to think about it.# ~/.config/i3/config
# ── WinJitsu daemon ──────────────────────────────────────────────────────────
exec_always --no-startup-id winjitsu --daemon
# ── Grid snapping ────────────────────────────────────────────────────────────
bindsym $mod+Up exec winjitsu N
bindsym $mod+Down exec winjitsu S
bindsym $mod+Right exec winjitsu E
bindsym $mod+Left exec winjitsu W
# ── Corner snapping ──────────────────────────────────────────────────────────
bindsym $mod+Shift+Up exec winjitsu NE
bindsym $mod+Shift+Left exec winjitsu NW
bindsym $mod+Shift+Down exec winjitsu SW
bindsym $mod+Shift+Right exec winjitsu SE
# ── Center / Fullscreen / Restore ────────────────────────────────────────────
bindsym $mod+c exec winjitsu C
bindsym $mod+f exec winjitsu F
bindsym $mod+u exec winjitsu U
bindsym $mod+t exec winjitsu TF
# ── Multi-monitor ────────────────────────────────────────────────────────────
bindsym $mod+Shift+m exec winjitsu TD
$mod+Shift+r. The daemon will restart automatically thanks to exec_always. GNOME does not have a plain text config file for keybindings. You can set custom shortcuts either through Settings → Keyboard → Keyboard Shortcuts → Custom Shortcuts, or via gsettings from the terminal.Autostart the daemon first. GNOME does not directly support running persistent background processes via hotkeys. Create a .desktop autostart file instead:mkdir -p ~/.config/autostart
cat > ~/.config/autostart/winjitsu-daemon.desktop << 'EOF'
[Desktop Entry]
Type=Application
Name=WinJitsu Daemon
Exec=winjitsu --daemon
Hidden=false
NoDisplay=false
X-GNOME-Autostart-enabled=true
EOF
gsettings (example for winjitsu N on Super+Up):# 1. Pick a free custom-keybinding slot (e.g. custom0)
SLOT="/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/custom0/"
# 2. Define the binding
gsettings set org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/custom0/ name "WinJitsu North"
gsettings set org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/custom0/ command "winjitsu N"
gsettings set org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/custom0/ binding "<Super>Up"
# 3. Register the slot in the list of active custom bindings
gsettings set org.gnome.settings-daemon.plugins.media-keys custom-keybindings \
"['/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/custom0/']"
custom1, custom2, …) and appending each new path to the list in step 3.GNOME’s custom keybinding infrastructure spawns a new process per keypress, so there is a small overhead compared to i3 or Openbox. The WinJitsu daemon absorbs this — the action still fires smoothly because the client command is near-instant.
KDE Plasma lets you define custom shortcuts in System Settings → Shortcuts → Custom Shortcuts. Each shortcut triggers a shell command directly.Autostart the daemon. Go to System Settings → Autostart, click Add Login Script, and enter winjitsu --daemon as the command. Set the trigger to At Login.Alternatively, create the autostart entry from the terminal:mkdir -p ~/.config/autostart
cat > ~/.config/autostart/winjitsu-daemon.desktop << 'EOF'
[Desktop Entry]
Type=Application
Name=WinJitsu Daemon
Exec=winjitsu --daemon
Hidden=false
X-KDE-autostart-enabled=true
EOF
- Open System Settings → Shortcuts → Custom Shortcuts.
- Click Edit → New → Global Shortcut → Command/URL.
- Name it (e.g.
WinJitsu North).
- Under the Trigger tab, click the button and press your desired key combination (e.g.
Super+Up).
- Under the Action tab, enter the command:
winjitsu N.
- Click Apply.
Repeat for each action. Example commands to enter in the Action tab:winjitsu N # Super+Up → top half
winjitsu S # Super+Down → bottom half
winjitsu E # Super+Right → right half
winjitsu W # Super+Left → left half
winjitsu NE # Super+Shift+Up → top-right quarter
winjitsu NW # Super+Shift+Left → top-left quarter
winjitsu SE # Super+Shift+Right → bottom-right quarter
winjitsu SW # Super+Shift+Down → bottom-left quarter
winjitsu C # Super+C → center
winjitsu F # Super+F → fullscreen
winjitsu U # Super+U → restore
winjitsu TF # Super+T → toggle fullscreen
winjitsu TD # Super+Shift+M → next monitor
Openbox keybindings live in ~/.config/openbox/rc.xml inside the <keyboard> section, and the daemon can be autostarted from ~/.config/openbox/autostart.Autostart the daemon by adding one line to ~/.config/openbox/autostart:# ~/.config/openbox/autostart
winjitsu --daemon &
rc.xml — add these <keybind> elements inside the existing <keyboard> block:<!-- ~/.config/openbox/rc.xml (inside <keyboard>) -->
<!-- Grid snapping -->
<keybind key="W-Up">
<action name="Execute"><command>winjitsu N</command></action>
</keybind>
<keybind key="W-Down">
<action name="Execute"><command>winjitsu S</command></action>
</keybind>
<keybind key="W-Right">
<action name="Execute"><command>winjitsu E</command></action>
</keybind>
<keybind key="W-Left">
<action name="Execute"><command>winjitsu W</command></action>
</keybind>
<!-- Corner snapping -->
<keybind key="W-S-Up">
<action name="Execute"><command>winjitsu NE</command></action>
</keybind>
<keybind key="W-S-Left">
<action name="Execute"><command>winjitsu NW</command></action>
</keybind>
<keybind key="W-S-Down">
<action name="Execute"><command>winjitsu SW</command></action>
</keybind>
<keybind key="W-S-Right">
<action name="Execute"><command>winjitsu SE</command></action>
</keybind>
<!-- Center / Fullscreen / Restore -->
<keybind key="W-c">
<action name="Execute"><command>winjitsu C</command></action>
</keybind>
<keybind key="W-f">
<action name="Execute"><command>winjitsu F</command></action>
</keybind>
<keybind key="W-u">
<action name="Execute"><command>winjitsu U</command></action>
</keybind>
<keybind key="W-t">
<action name="Execute"><command>winjitsu TF</command></action>
</keybind>
<!-- Multi-monitor -->
<keybind key="W-S-m">
<action name="Execute"><command>winjitsu TD</command></action>
</keybind>
W is the Super (Windows) key and S is Shift. After editing rc.xml, apply changes with: Debounce and Key Repeat
WinJitsu’s daemon applies a configurable debounce delay before executing any action. Rapid keypresses within delay_ms (default 250 ms) collapse into a single action — only the last command in the burst fires. This means holding a key down with key-repeat enabled will not cause the window to stutter through multiple intermediate positions; it will simply animate once to the final target when you release the key. You can tune the delay with --delay-ms or by editing delay_ms in the [daemon] section of ~/.config/winjitsu/config.ini.