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.
Actions are single uppercase strings passed directly to the winjitsu CLI — for example, winjitsu NE or winjitsu TF. Each invocation connects to the running daemon over a Unix socket, sends the action code followed by a newline, and waits for a response before exiting. Inside the daemon, a dispatcher routes the code to its handler function: direction codes (N, S, E, W, NE, NW, SE, SW, C) all map to the direction() handler, while the remaining codes have dedicated handlers registered in _ACTION_HANDLERS.
All nine grid-snapping actions (N, S, E, W, NE, NW, SE, SW, C) automatically save the window’s pre-snap geometry to the SQLite cache at ~/.cache/winjitsu/state.db. This is what makes U (restore) work after any snapping operation.
Grid snapping
Grid actions divide the current monitor into halves and quarters and place the active window into the chosen cell. The window’s position and size are derived from the screen’s origin coordinates and dimensions as reported by RandR, so grid snapping always targets the monitor the window is currently on.
| Action | Width | Height | X origin | Y origin | Description |
|---|
N | full screen width | half screen height | screen left | screen top | Top half — full width, upper half |
S | full screen width | half screen height | screen left | screen top + ½ height | Bottom half — full width, lower half |
E | half screen width | full screen height | screen left + ½ width | screen top | Right half — right column, full height |
W | half screen width | full screen height | screen left | screen top | Left half — left column, full height |
NE | half screen width | half screen height | screen left + ½ width | screen top | Top-right quarter |
NW | half screen width | half screen height | screen left | screen top | Top-left quarter |
SE | half screen width | half screen height | screen left + ½ width | screen top + ½ height | Bottom-right quarter |
SW | half screen width | half screen height | screen left | screen top + ½ height | Bottom-left quarter |
C | window’s current width | window’s current height | centered horizontally | centered vertically | Center on screen — preserves window size |
# Snap the active window to the left half
winjitsu W
# Snap to the top-right quarter
winjitsu NE
# Center without resizing
winjitsu C
Fullscreen
The three fullscreen actions use cfg.padding (default 0 px) to determine how much border to leave around the window. They share state through the SQLite cache so that U and TF know where the window was before it was fullscreened.
| Action | Description |
|---|
F | Fills the entire monitor, inset by padding px on each side. Target size is (screen_width - 2×padding) × (screen_height - 2×padding). |
U | Restores the window to the geometry saved in the SQLite cache. Returns WARN: no cached state for this window if no entry exists. |
TF | Checks whether the window already occupies fullscreen dimensions (accounting for padding). If it does, calls U (restore). If it does not, calls F (fullscreen). |
# Fullscreen the active window (no gaps)
winjitsu F
# Fullscreen with 8 px padding (requires daemon started with --padding 8)
winjitsu F
# Toggle between fullscreen and previous size/position
winjitsu TF
# Restore to saved position
winjitsu U
Display
TD moves the active window to the next monitor in the RandR output list, cycling back to the first monitor after the last one.
The action preserves the window’s relative offset on the new monitor: it calculates the offset the window has from the top-left corner of the current monitor and applies that same offset on the target monitor. The result is clamped to the target screen’s bounds so the window cannot be moved off-screen. After moving, the new position is saved to the SQLite cache.
| Action | Description |
|---|
TD | Move the active window to the next monitor in the RandR list, preserving relative position. |
# Send the active window to the next monitor
winjitsu TD
Cache
CC wipes all saved window states from the SQLite database at ~/.cache/winjitsu/state.db by executing DELETE FROM windows. It is a no-op if the database file does not exist.
After running CC, any subsequent U (restore) call will respond with WARN: no cached state for this window until new state is written by a grid or fullscreen action.
| Action | Description |
|---|
CC | Deletes all rows from the windows table in the SQLite cache. |
# Clear all saved window positions
winjitsu CC