OXWM(1)

NAME
oxwm - a dynamic tiling window manager for X11 written in Zig

SYNOPSIS
oxwm [OPTIONS]

DESCRIPTION
oxwm is a lightweight, dynamic tiling window manager for X11 inspired by dwm but ditching the suckless philosophy. Configuration is done via a runtime-loadable Lua config file, allowing instant hot-reload without recompilation.

Features include tag-based workspaces, multiple layouts (tiling, floating, monocle, grid, tabbed), configurable gaps, a modular status bar, keychord support, window rules, autostart commands, multi-monitor support, and persistent window state across restarts.

OPTIONS

--init
    Create default config file at ~/.config/oxwm/config.lua

--config PATH
    Use a custom config file at the specified path

--version
    Print version information and exit

--help
    Print help message and exit

CONFIGURATION
oxwm reads its configuration from ~/.config/oxwm/config.lua. If no config exists on first launch, a default template will be created automatically.

The config file uses Lua and provides a comprehensive API for customization:

•   Keybindings (including multi-key keychords)

•   Colors and appearance (borders, gaps)

•   Status bar blocks (battery, RAM, datetime, shell commands, static text)

•   Window rules (per-application settings)

•   Autostart commands

•   Layout symbols

•   Tag names (supports Unicode/Nerd Font icons)

After editing the config, reload with Mod+Shift+R – no compilation or X restart required.

LSP support is available via the ~/.config/oxwm/oxwm.lua type definitions file for autocomplete in editors.

DEFAULT KEYBINDINGS
The default modifier key is Super (Mod4). All bindings are customizable in config.lua.

  Window Management

Super+Return
    Spawn terminal (default: alacritty)

Super+Q
    Kill focused window

Super+J, Super+K
    Cycle focus down/up through windows

Super+Shift+J, Super+Shift+K
    Move window down/up in stack (swap position)

Super+Shift+Space
    Toggle floating mode for focused window

Super+Shift+F
    Toggle fullscreen for focused window

  Layouts

Super+F
    Switch to normie (floating) layout

Super+C
    Switch to tiling layout

Super+N
    Cycle through available layouts

Super+A
    Toggle gaps on/off

  Master Area (Tiling Layout)

Super+H
    Decrease master area width

Super+L
    Increase master area width

Super+I
    Increment number of master windows

Super+P
    Decrement number of master windows

  Tags (Workspaces)

Super+1..9
    View tag 1-9

Super+Shift+1..9
    Move focused window to tag 1-9

Super+Control+1..9
    Toggle multi-tag viewing (view multiple tags simultaneously)

Super+Control+Shift+1..9
    Toggle window on multiple tags (sticky window)

  Monitors

Super+Comma
    Focus previous monitor

Super+Period
    Focus next monitor

Super+Shift+Comma
    Send window to previous monitor

Super+Shift+Period
    Send window to next monitor

  Launchers

Super+D
    Launch dmenu

Super+S
    Take screenshot with maim (selection to clipboard)

  Window Manager

Super+Shift+Q
    Quit oxwm

Super+Shift+R
    Hot reload oxwm (reload config without restarting X)

Super+Shift+/
    Show keybindings overlay

MOUSE BINDINGS

Super+Button1 (drag)
    Move window in floating mode

Super+Button3 (drag)
    Resize window in floating mode

Clicking on a tag number in the status bar switches to that tag.

LAYOUTS
oxwm provides the following layouts:

Tiling
    Master/stack layout with adjustable master area size and number of master windows.

Normie
    Floating-by-default layout where windows can be freely positioned.

Monocle
    Fullscreen stacking layout showing one window at a time per tag.

Grid
    Equal-sized grid layout distributing windows evenly.

Tabbed
    Tabbed container layout with a tab bar for switching between windows.

KEYCHORDS
oxwm supports multi-key sequences called keychords. These allow binding commands to sequences like "Super+Space then T".

Example keychord in config.lua:

        oxwm.key.chord({
            { modifiers = { "Mod4" }, key = "space" },
            { modifiers = {}, key = "t" },
        }, oxwm.spawn_terminal)

Press Escape to cancel any in-progress keychord sequence.

WINDOW RULES
Window rules allow per-application settings based on window class, instance, or title:

        oxwm.rule.add({
            class = "Firefox",
            floating = false,
            tag = 2,
        })

Rule properties:

•   class - Match window class (substring)

•   instance - Match window instance (substring)

•   title - Match window title (substring)

•   floating - Force floating mode (true/false)

•   tag - Auto-assign to specific tag (1-9)

•   monitor - Auto-assign to specific monitor

STATUS BAR
The status bar displays tags, layout indicator, window title, and customizable blocks.

  Block Types

DateTime
    Date/time with customizable format string

RAM RAM usage display (used/total)

Battery
    Battery status with charging/discharging/full states

Shell
    Execute shell command and display output

Static
    Static text display

  Block Configuration
Each block supports:

•   color - Text color (hex: #RRGGBB or 0xRRGGBB)

•   underline - Underline color

•   interval - Update interval in seconds

  Color Schemes
Tag colors can be customized for three states:

•   Normal - Unoccupied tags

•   Occupied - Tags containing windows

•   Selected - Currently viewed tag

LUA API
The configuration uses the following Lua API modules:

  Core Functions

oxwm.set_terminal(term)
    Set terminal emulator

oxwm.set_modkey(modkey)
    Set modifier key (Mod1-5, Shift, Control)

oxwm.set_tags(tags)
    Define workspace tag names

oxwm.autostart(cmd)
    Add autostart command

oxwm.spawn(cmd)
    Spawn command/program

oxwm.spawn_terminal()
    Spawn configured terminal

oxwm.quit()
    Quit window manager

oxwm.restart()
    Restart window manager

oxwm.show_keybinds()
    Show keybindings overlay

  Key Bindings (oxwm.key)

oxwm.key.bind(modifiers, key, action)
    Single key binding

oxwm.key.chord(keyseq, action)
    Multi-key sequence binding

  Border (oxwm.border)

oxwm.border.set_width(pixels)

oxwm.border.set_focused_color(color)

oxwm.border.set_unfocused_color(color)

  Gaps (oxwm.gaps)

oxwm.gaps.set_enabled(bool)

oxwm.gaps.set_inner(h, v)

oxwm.gaps.set_outer(h, v)

oxwm.gaps.set_smart(bool)
    Enable smart gaps (no gaps with single window)

  Client (oxwm.client)

oxwm.client.kill()

oxwm.client.toggle_fullscreen()

oxwm.client.toggle_floating()

oxwm.client.focus_stack(direction)

oxwm.client.move_stack(direction)

  Layout (oxwm.layout)

oxwm.layout.set(name)
    Set specific layout ("tiling", "normie", "monocle", "grid", "tabbed")

oxwm.layout.cycle()

  Tag (oxwm.tag)

oxwm.tag.view(index)

oxwm.tag.toggleview(index)

oxwm.tag.move_to(index)

oxwm.tag.toggletag(index)

  Monitor (oxwm.monitor)

oxwm.monitor.focus(direction)
    Focus monitor (-1 prev, 1 next)

oxwm.monitor.tag(direction)
    Move window to monitor

  Bar (oxwm.bar)

oxwm.bar.set_font(font)
    Set bar font (XFT format)

oxwm.bar.set_blocks(blocks)
    Set status bar blocks

oxwm.bar.set_scheme_normal(fg, bg, ul)

oxwm.bar.set_scheme_occupied(fg, bg, ul)

oxwm.bar.set_scheme_selected(fg, bg, ul)

FILES

~/.config/oxwm/config.lua
    Main configuration file

~/.config/oxwm/oxwm.lua
    LSP type definitions for editor autocomplete

/usr/share/xsessions/oxwm.desktop
    X session desktop entry (if installed via package manager)

ENVIRONMENT

DISPLAY
    X11 display to connect to (standard X11 variable)

XDG_CONFIG_HOME
    Custom config directory (default: ~/.config)

HOME
    Home directory for config location

EXAMPLES

Start oxwm normally:
            oxwm

Initialize config file:
            oxwm --init

Use custom config:
            oxwm --config ~/my-oxwm-config.lua

Test in Xephyr (nested X server):
            Xephyr -screen 1280x800 :1 &
            DISPLAY=:1 oxwm

TESTING
Test oxwm without affecting your current session using Xephyr:

        # Start nested X server
        Xephyr -screen 1280x800 :1 &
        # Run oxwm in it
        DISPLAY=:1 oxwm

BUGS
Report bugs at: https://github.com/tonybanters/oxwm/issues

SEE ALSO
X(7), dwm(1), dmenu(1), xrandr(1), lua(1)

AUTHORS
Written by Tony (tonybtw).

Inspired by dwm but designed to be user-friendly and eliminate arbitrary elitism.

LICENSE
GPL v3 - see https://www.gnu.org/licenses/gpl-3.0.en.html