🪟 gar

Architecture

gar is built with a modular architecture separating X11 communication, window management logic, input handling, and IPC into distinct components.

X11 Connection

gar uses the x11rb crate for type-safe X11 protocol communication. On startup, it:

1. Connects to the X server via DISPLAY environment variable
2. Attempts to become the window manager by selecting SubstructureRedirect
3. Queries RandR for monitor configuration
4. Scans for existing windows and manages them

Event Loop

The main event loop handles X11 events, IPC commands, and signal interrupts:

• MapRequest - New window wants to be shown, trigger tiling
• UnmapNotify - Window hidden, adjust layout
• DestroyNotify - Window destroyed, remove from tree
• ConfigureRequest - Window resize/move request
• KeyPress - Keyboard input for keybindings
• PropertyNotify - EWMH property changes

Window Management

Windows are organized in a binary tree structure per workspace. Each node is either:

• Container - Internal node with split direction (horizontal/vertical) and two children
• Leaf - Terminal node containing a single window

This structure enables efficient resize operations and automatic layout rebalancing.

Lua Integration

Configuration is powered by mlua with Lua 5.4. The gar global table provides:

• gar.set(key, value) - Set configuration option
• gar.bind(keys, fn) - Bind key combination to function
• gar.exec(cmd) - Execute shell command
• gar.exec_once(cmd) - Execute once per session (autostart)
• gar.focus(dir) - Focus window in direction
• gar.swap(dir) - Swap with neighbor
• gar.workspace(n) - Switch to workspace

Tiling System

gar uses a binary space partitioning approach where each new window splits the focused container.

Smart Splits

When a new window is created, gar determines the split direction based on the focused container's aspect ratio:

• If container is wider than tall → split horizontally (side by side)
• If container is taller than wide → split vertically (stacked)

This produces balanced layouts without manual direction specification.

Resize Operations

Use Mod+Ctrl+h/j/k/l to resize windows. Resize operations adjust the split ratio of the parent container, affecting both siblings proportionally.

Equalize Layout

Press Mod+e to reset all split ratios to 50/50, making all windows in the current workspace equal size.

Workspaces

gar provides 10 workspaces per monitor, numbered 1-10 (0 key for workspace 10).

Navigation

Switch workspaces with Mod+1 through Mod+0. Each workspace maintains its own window tree independently.

Moving Windows

Move the focused window to another workspace with Mod+Shift+1 through Mod+Shift+0. If follow_window_on_move is enabled, focus follows the window.

Cycling

Use Mod+Tab and Mod+Shift+Tab to cycle through workspaces sequentially.

Multi-Monitor

gar supports multiple monitors with independent workspace sets per output.

RandR Support

Monitor configuration is detected via X RandR extension. gar responds to hotplug events for monitor connect/disconnect.

Monitor Focus

Use Mod+, and Mod+. to move focus between monitors (previous/next).

Window Transfer

Move windows between monitors with Mod+Shift+, and Mod+Shift+..

Monitor Ordering

Override automatic monitor detection order with monitor_order:

-- Specify left-to-right monitor order
gar.set("monitor_order", { "DP-1", "eDP-1", "HDMI-1" })

This affects how Mod+, and Mod+. navigate between monitors.

Floating Windows

Toggle floating mode with Mod+f. Floating windows:

• Are removed from the tiling tree
• Can be freely positioned and resized
• Float above tiled windows in stacking order
• Maintain their own stacking order (last focused = top)
• Cycle through with Mod+`

Fullscreen mode (Mod+Shift+f) temporarily removes a window from tiling and maximizes it to the full monitor dimensions.

Window Rules

Automatically apply settings to windows based on their properties using gar.rule().

Match Criteria

Match windows using WM_CLASS (class/instance) or window title:

-- Use xprop to find window class/instance
-- class = WM_CLASS second value
-- instance = WM_CLASS first value
gar.rule({ class = "Firefox" }, { floating = false })
gar.rule({ instance = "Navigator" }, { workspace = 2 })
gar.rule({ title = "Picture-in-Picture" }, { floating = true })

Rule Actions

Available actions when a rule matches:

• floating = true/false - Force floating or tiled mode
• workspace = n - Send window to specific workspace

-- Example: Music apps to workspace 9
gar.rule({ class = "Spotify" }, { workspace = 9 })
gar.rule({ class = "cider" }, { workspace = 9, floating = false })

Compositor Integration

gar supports multiple compositors for visual effects. Set with gar.set("compositor", "..."):

• "picom" (default) - Full-featured X11 compositor with blur, shadows, animations
• "garchomp" - gardesk native compositor (X11, gartk-based)
• "none" - Disable compositor management

picom Configuration

gar auto-generates ~/.config/gar/picom.conf from your Lua settings. The configuration is regenerated on reload and picom is signaled to reread it.

Key picom settings controlled via gar.set():

• corner_radius - Window corner rounding
• blur_enabled, blur_method, blur_strength - Background blur
• shadow_enabled, shadow_radius, shadow_opacity - Drop shadows
• opacity_focused, opacity_unfocused - Window transparency

Per-Window picom Rules

Apply compositor effects to specific windows with gar.picom_rule():

-- Terminal with blur
gar.picom_rule({
    match = "class_g = 'Alacritty'",
    blur_background = true,
    opacity = 0.92,
})

-- Disable shadows for panels
gar.picom_rule({
    match = "window_type = 'dock'",
    shadow = false,
})

Match syntax uses picom expressions: class_g (class), class_i (instance), name (title), window_type.

Animations

Window open/close animations require picom v12 or newer:

-- Animation settings
gar.set("animation_open", "fly-in")    -- slide-in, fly-in, appear, none
gar.set("animation_close", "fly-out")  -- slide-out, fly-out, disappear, none
gar.set("animation_duration", 0.15)    -- seconds

Custom Shaders

Apply GLSL shaders globally or per-window (requires picom GLX backend):

-- Global shader
gar.set("picom_shader", "~/.config/gar/shaders/focused-glow.glsl")

-- Per-window shader
gar.picom_rule({
    match = "class_g = 'mpv'",
    shader = "~/.config/gar/shaders/vibrance.glsl",
})

gardesk Ecosystem

gar integrates deeply with the gardesk desktop environment components through Lua configuration tables and native IPC.

garbar Integration

Define the gar.bar table to enable automatic garbar management:

gar.bar = {
    height = 32,
    position = "top",
    background = "#1a1a1a",
    foreground = "#ffffff",
    modules_left = { "workspaces", "window_title" },
    modules_right = { "cpu", "memory", "datetime" },
}

When gar.bar is present, gar spawns garbar automatically and reserves screen space for it. See garbar documentation for full configuration.

garterm Integration

Define the gar.terminal table for garterm configuration:

gar.terminal = {
    shell = "/usr/bin/fish",
    font = { family = "JetBrainsMono Nerd Font", size = 20.0 },
    colors = { preset = "catpuccin-mocha" },
    sessions = {
        ["dev"] = {
            tabs = {
                { title = "Editor", cwd = "~/project", cmd = "nvim" },
                { title = "Server", cwd = "~/project", cmd = "npm run dev" },
            },
        },
    },
}

See garterm documentation for full configuration.

garnotify Integration

Define the gar.notification table to enable garnotify:

gar.notification = {
    position = "top-right",
    width = 300,
    timeout = 5000,
}

When present, gar spawns garnotify automatically for D-Bus notifications.

Process Management

gar tracks processes spawned via gar.exec() and gar.exec_once(). On exit, gar sends SIGTERM to all spawned process groups.

• gar.exec(cmd) - Run command every time (on keybind, etc.)
• gar.exec_once(cmd) - Run only once per session (autostart)

Both functions spawn processes as their own process group leaders, so killing the group terminates child processes too (e.g., sh -c "garterm" kills both sh and garterm).

EWMH Compliance

gar implements the Extended Window Manager Hints specification for interoperability with:

• Status bars (garbar, polybar, waybar)
• Application launchers (garlaunch, rofi, dmenu)
• Notification daemons (garnotify, dunst)
• Pagers and taskbars

Supported EWMH atoms include:

• _NET_SUPPORTED, _NET_SUPPORTING_WM_CHECK
• _NET_CLIENT_LIST, _NET_CLIENT_LIST_STACKING
• _NET_NUMBER_OF_DESKTOPS, _NET_CURRENT_DESKTOP
• _NET_ACTIVE_WINDOW, _NET_WM_STATE
• _NET_WM_WINDOW_TYPE, _NET_WORKAREA