OXWM(1)

📦 version 0.12.0, in nixos 26.05, nixpkgs unstable

💅 OXWM(1) — the manual page, but make it slay

okay so bestie, you're reading the oxwm man page and honestly? iconic of you. let's get into it 🫶

✨ NAME ✨

oxwm — a dynamic tiling window manager for X11 written in Zig 🦋

✨ SYNOPSIS ✨

oxwm [OPTIONS]

🎀 DESCRIPTION 🎀

So oxwm is a lightweight, dynamic tiling window manager for X11, and the whole vibe is "inspired by dwm but we ditched the suckless philosophy" — no cap. 💅

Configuration happens through a runtime-loadable Lua config file, which means instant hot-reload and you literally never have to recompile. not me, not recompiling, ever 😭✨

The features are giving main character energy:

  • 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
  • persistent window state across restarts

💖 OPTIONS 💖

  • --init — creates the 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 config from ~/.config/oxwm/config.lua. If there's no config on first launch, a default template gets created automatically — so thoughtful of it 🥹

The config file uses Lua and hands you a comprehensive API for customization, like:

  • 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, no X restart, nothing. obsessed.

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). Every single binding here is customizable in config.lua, iykyk.

🪟 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

Also: clicking on a tag number in the status bar switches to that tag. tiny detail, big convenience 💅

🦋 LAYOUTS 🦋

oxwm provides these layouts, bestie:

  • 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 let you bind commands to sequences like "Super+Space then T". yes, a combo. a little key combo meal 🍓

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. lifesaver fr 😌

🪟 WINDOW RULES 🪟

Window rules let you do 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, the layout indicator, the window title, and customizable blocks. it's giving customizable dashboard 💜

🧱 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 — genuinely the move, bestie 🙈

# 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

(be nice, they're doing their best 🫶)

🔗 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. periodt. ✨

📜 LICENSE 📜

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

okay that's the whole thing, you're officially caught up 💖 this was oxwm version 0.8.0, dated 2025-12-08 — go forth and tile, queen 👑

📦 where this page comes from