tonybanters / oxwm

# OXWM: DWM but Better
A dynamic window manager written in Zig, inspired by dwm but designed to evolve beyond it. OXWM features a clean, functional Lua API for configuration with hot-reloading support, ditching the suckless philosophy of *"edit + recompile"*. Instead, we focus on lowering friction for users with sane defaults, LSP-powered autocomplete, and instant configuration changes without restarting your X session.
**Documentation:** ox-docs.vercel.app
## Showcase
Setups from OXWM users across Arch, CachyOS, Debian and FreeBSD.
## Installation
### NixOS (nixpkgs)
Add OXWM to your `configuration.nix` like so:
 [code] 
#### Initialize your config
After rebuilding your system with `sudo nixos-rebuild switch`, log in via your display manager.
On first launch, your initial config file will be automatically created and placed in `~/.config/oxwm/config.lua`. Edit it and reload with `Mod+Shift+R`.
#### Development setup with Nix
For development, use the provided dev shell:
 [code] 
### Arch Linux
AUR: oxwm-git
 [code] 
This will automatically put a desktop session file into your xsessions directory.
Manually, install the dependencies and see Building from Source:
 [code] 
### Building from Source
Note, on many BSD systems, the zig compiler will aggressively attempt to remove debug symbols which is causing a known linker issue. Please use this method on BSD:
 [code] 
On other legacy distros, just use:
 [code] 
### Setting up OXWM
#### Without a display manager (startx)
Add the following to your `~/.xinitrc`:
 [code] 
Then start X with:
 [code] 
#### With a display manager
If using a display manager (LightDM, GDM, SDDM), OXWM should appear in the session list after installation.
## Configuration
OXWM uses a clean, functional Lua API for configuration. On first run, a default config is automatically created at `~/.config/oxwm/config.lua`.
### Quick Example
Here's what the functional API looks like:
 [code] 
### Key Configuration Areas
Edit `~/.config/oxwm/config.lua` to customize:
- Basic settings (terminal, modkey, tags)
- Borders and colors
- Window gaps
- Status bar (font, blocks, color schemes)
- Keybindings and keychords
- Layouts, layout symbols, and attach method
- Window rules
- Autostart commands
After making changes, reload OXWM with `Mod+Shift+R`.
### Creating Your Config
Generate the default config:
 [code] 
Or just start OXWM. It will create one automatically on first run.
## Contributing
When contributing to OXWM:
1. Never commit your personal `~/.config/oxwm/config.lua`
2. Only modify `templates/config.lua` if adding new configuration options
3. Test your changes with `zig build xephyr` using Xephyr or `zig build xwayland` using Xwayland
4. Document any new features or keybindings
## Key Bindings
Default keybindings (fully customizable in `~/.config/oxwm/config.lua`):
| Binding | Action |
|------------------------|-----------------------------------|
| Super+Return | Spawn terminal |
| Super+J/K | Cycle focus through stack |
| Super+Q |