oxwm

.TH OXWM 1 "2025-12-08" "oxwm 0.8.0" "User Commands"

.SH NAME

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

.SH SYNOPSIS

.B oxwm

[\fIOPTIONS\fR]

.SH DESCRIPTION

.B 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.

.PP

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.

.SH OPTIONS

.TP

.B \-\-init

Create default config file at

.IR ~/.config/oxwm/config.lua

.TP

.B \-\-config \fIPATH\fR

Use a custom config file at the specified path

.TP

.B \-\-version

Print version information and exit

.TP

.B \-\-help

Print help message and exit

.SH CONFIGURATION

.B oxwm

reads its configuration from

.IR ~/.config/oxwm/config.lua .

If no config exists on first launch, a default template will be created automatically.

.PP

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

.IP \(bu 2

Keybindings (including multi-key keychords)

.IP \(bu 2

Colors and appearance (borders, gaps)

.IP \(bu 2

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

.IP \(bu 2

Window rules (per-application settings)

.IP \(bu 2

Autostart commands

.IP \(bu 2

Layout symbols

.IP \(bu 2

Tag names (supports Unicode/Nerd Font icons)

.PP

After editing the config, reload with

.B Mod+Shift+R

\(en no compilation or X restart required.

.PP

LSP support is available via the

.I ~/.config/oxwm/oxwm.lua

type definitions file for autocomplete in editors.

.SH DEFAULT KEYBINDINGS

The default modifier key is

.B Super

(Mod4). All bindings are customizable in config.lua.

.SS Window Management

.TP

.B Super+Return

Spawn terminal (default: alacritty)

.TP

.B Super+Q

Kill focused window

.TP

.B Super+J, Super+K

Cycle focus down/up through windows

.TP

.B Super+Shift+J, Super+Shift+K

Move window down/up in stack (swap position)

.TP

.B Super+Shift+Space

Toggle floating mode for focused window

.TP

.B Super+Shift+F

Toggle fullscreen for focused window

.SS Layouts

.TP

.B Super+F

Switch to normie (floating) layout

.TP

.B Super+C

Switch to tiling layout

.TP

.B Super+N

Cycle through available layouts

.TP

.B Super+A

Toggle gaps on/off

.SS Master Area (Tiling Layout)

.TP

.B Super+H

Decrease master area width

.TP

.B Super+L

Increase master area width

.TP

.B Super+I

Increment number of master windows

.TP

.B Super+P

Decrement number of master windows

.SS Tags (Workspaces)

.TP

.B Super+1..9

View tag 1-9

.TP

.B Super+Shift+1..9

Move focused window to tag 1-9

.TP

.B Super+Control+1..9

Toggle multi-tag viewing (view multiple tags simultaneously)

.TP

.B Super+Control+Shift+1..9

Toggle window on multiple tags (sticky window)

.SS Monitors

.TP

.B Super+Comma

Focus previous monitor

.TP

.B Super+Period

Focus next monitor

.TP

.B Super+Shift+Comma

Send window to previous monitor

.TP

.B Super+Shift+Period

Send window to next monitor

.SS Launchers

.TP

.B Super+D

Launch dmenu

.TP

.B Super+S

Take screenshot with maim (selection to clipboard)

.SS Window Manager

.TP

.B Super+Shift+Q

Quit oxwm

.TP

.B Super+Shift+R

Hot reload oxwm (reload config without restarting X)

.TP

.B Super+Shift+/

Show keybindings overlay

.SH MOUSE BINDINGS

.TP

.B Super+Button1 (drag)

Move window in floating mode

.TP

.B Super+Button3 (drag)

Resize window in floating mode

.PP

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

.SH LAYOUTS

.B oxwm

provides the following layouts:

.TP

.B Tiling

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

.TP

.B Normie

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

.TP

.B Monocle

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

.TP

.B Grid

Equal-sized grid layout distributing windows evenly.

.TP

.B Tabbed

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

.SH KEYCHORDS

.B oxwm

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

.PP

Example keychord in config.lua:

.PP

.EX

    oxwm.key.chord({

        { modifiers = { "Mod4" }, key = "space" },

        { modifiers = {}, key = "t" },

    }, oxwm.spawn_terminal)

.EE

.PP

Press

.B Escape

to cancel any in-progress keychord sequence.

.SH WINDOW RULES

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

.PP

.EX

    oxwm.rule.add({

        class = "Firefox",

        floating = false,

        tag = 2,

    })

.EE

.PP

Rule properties:

.IP \(bu 2

.B class

\- Match window class (substring)

.IP \(bu 2

.B instance

\- Match window instance (substring)

.IP \(bu 2

.B title

\- Match window title (substring)

.IP \(bu 2

.B floating

\- Force floating mode (true/false)

.IP \(bu 2

.B tag

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

.IP \(bu 2

.B monitor

\- Auto-assign to specific monitor

.SH STATUS BAR

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

.SS Block Types

.TP

.B DateTime

Date/time with customizable format string

.TP

.B RAM

RAM usage display (used/total)

.TP

.B Battery

Battery status with charging/discharging/full states

.TP

.B Shell

Execute shell command and display output

.TP

.B Static

Static text display

.SS Block Configuration

Each block supports:

.IP \(bu 2

.B color

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

.IP \(bu 2

.B underline

\- Underline color

.IP \(bu 2

.B interval

\- Update interval in seconds

.SS Color Schemes

Tag colors can be customized for three states:

.IP \(bu 2

.B Normal

\- Unoccupied tags

.IP \(bu 2

.B Occupied

\- Tags containing windows

.IP \(bu 2

.B Selected

\- Currently viewed tag

.SH LUA API

The configuration uses the following Lua API modules:

.SS Core Functions

.TP

.B oxwm.set_terminal(term)

Set terminal emulator

.TP

.B oxwm.set_modkey(modkey)

Set modifier key (Mod1-5, Shift, Control)

.TP

.B oxwm.set_tags(tags)

Define workspace tag names

.TP

.B oxwm.autostart(cmd)

Add autostart command

.TP

.B oxwm.spawn(cmd)

Spawn command/program

.TP

.B oxwm.spawn_terminal()

Spawn configured terminal

.TP

.B oxwm.quit()

Quit window manager

.TP

.B oxwm.restart()

Restart window manager

.TP

.B oxwm.show_keybinds()

Show keybindings overlay

.SS Key Bindings (oxwm.key)

.TP

.B oxwm.key.bind(modifiers, key, action)

Single key binding

.TP

.B oxwm.key.chord(keyseq, action)

Multi-key sequence binding

.SS Border (oxwm.border)

.TP

.B oxwm.border.set_width(pixels)

.TP

.B oxwm.border.set_focused_color(color)

.TP

.B oxwm.border.set_unfocused_color(color)

.SS Gaps (oxwm.gaps)

.TP

.B oxwm.gaps.set_enabled(bool)

.TP

.B oxwm.gaps.set_inner(h, v)

.TP

.B oxwm.gaps.set_outer(h, v)

.TP

.B oxwm.gaps.set_smart(bool)

Enable smart gaps (no gaps with single window)

.SS Client (oxwm.client)

.TP

.B oxwm.client.kill()

.TP

.B oxwm.client.toggle_fullscreen()

.TP

.B oxwm.client.toggle_floating()

.TP

.B oxwm.client.focus_stack(direction)

.TP

.B oxwm.client.move_stack(direction)

.SS Layout (oxwm.layout)

.TP

.B oxwm.layout.set(name)

Set specific layout ("tiling", "normie", "monocle", "grid", "tabbed")

.TP

.B oxwm.layout.cycle()

.SS Tag (oxwm.tag)

.TP

.B oxwm.tag.view(index)

.TP

.B oxwm.tag.toggleview(index)

.TP

.B oxwm.tag.move_to(index)

.TP

.B oxwm.tag.toggletag(index)

.SS Monitor (oxwm.monitor)

.TP

.B oxwm.monitor.focus(direction)

Focus monitor (-1 prev, 1 next)

.TP

.B oxwm.monitor.tag(direction)

Move window to monitor

.SS Bar (oxwm.bar)

.TP

.B oxwm.bar.set_font(font)

Set bar font (XFT format)

.TP

.B oxwm.bar.set_blocks(blocks)

Set status bar blocks

.TP

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

.TP

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

.TP

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

.SH FILES

.TP

.I ~/.config/oxwm/config.lua

Main configuration file

.TP

.I ~/.config/oxwm/oxwm.lua

LSP type definitions for editor autocomplete

.TP

.I /usr/share/xsessions/oxwm.desktop

X session desktop entry (if installed via package manager)

.SH ENVIRONMENT

.TP

.B DISPLAY

X11 display to connect to (standard X11 variable)

.TP

.B XDG_CONFIG_HOME

Custom config directory (default: ~/.config)

.TP

.B HOME

Home directory for config location

.SH EXAMPLES

.TP

Start oxwm normally:

.EX

    oxwm

.EE

.TP

Initialize config file:

.EX

    oxwm --init

.EE

.TP

Use custom config:

.EX

    oxwm --config ~/my-oxwm-config.lua

.EE

.TP

Test in Xephyr (nested X server):

.EX

    Xephyr -screen 1280x800 :1 &

    DISPLAY=:1 oxwm

.EE

.SH TESTING

Test oxwm without affecting your current session using Xephyr:

.PP

.EX

    # Start nested X server

    Xephyr -screen 1280x800 :1 &

    # Run oxwm in it

    DISPLAY=:1 oxwm

.EE

.SH BUGS

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

.SH SEE ALSO

.BR X (7),

.BR dwm (1),

.BR dmenu (1),

.BR xrandr (1),

.BR lua (1)

.SH AUTHORS

Written by Tony (tonybtw).

.PP

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

.SH LICENSE

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