commit e746ba3d3b21a47a81f78c6ec788ffc82320337b
from: Brett Fisher <code@brettfisher.xyz>
date: Thu May 21 03:04:48 2026 UTC

README.md: Initial commit.

commit - 9c5a3857480649bf34ac3a62c347b39c5e0a7b55
commit + e746ba3d3b21a47a81f78c6ec788ffc82320337b
blob - /dev/null
blob + a3e71d1d076674ec3f5881c6b37b576ca61be05d (mode 644)
--- /dev/null
+++ README.md
@@ -0,0 +1,93 @@
+# bxwm
+
+A very basic X window manager, a.k.a Brett's X window manager.
+
+## Yet Another Window Manager?
+
+I went down the path of minimalist window managers a very long time  
+ago. I used [dwm](https://dwm.suckless.org/) for many years. I briefly  
+tried out both [i3](https://i3wm.org/) and [bspwm](https://github.com/baskerville/bspwm). I've relied on [cwm](https://cvsweb.openbsd.org/xenocara/app/cwm/) for the most recent several years.
+
+One day when I should've been working, I daydreamed about a window  
+manager that did nothing more nor less than what I needed a window  
+manager to do. That matched my worflow without tweaking or patching  
+or scripting or hacking.
+
+Dreaming led to finding minimal window manager source code, then  
+learning to read C code, then designing, then roadmapping, then  
+stumbling along writing C code, a lot of trial and error. And voila.
+
+Here is yet another window manager. My window manager. __bxwm__.  
+A stacking window manager that is purposely opinionated regarding  
+window placement and sizing, provides a straight forward work  
+environment, and prefers simplicity and tranquility.
+
+In addition to being the window manager I use every day, __bxwm__  
+also serves as my primary project for transitioning from writing  
+shell scripts for automating workflow to writing robust, maintainable  
+C programs that adhere to my values of minimalism, the Unix  
+philosophy, and clean, readable API design.
+
+## Dependencies
+
+  - Xlib
+  - A C compiler compliant with the C11 standard (e.g. cproc or gcc).
+  - bxhkd, basic X hotkey daemon  (required for managing key commands).
+
+## Build
+
+To build __bxwm__ from source.
+
+```
+make
+```
+
+## Install
+
+Install the binary and man page. Note that root privileges are not required as the default desination is `$HOME/.local/`.
+
+```
+make install
+```
+
+## Uninstall
+
+Remove the binary and man page.
+
+```
+make uninstall
+```
+
+## Configuration
+
+__bxwm__ is configured at compile-time by editing config.def.h. After making changes, the program must be recompiled and reinstalled. See bxwm(1) for details.
+
+## Design & Functionality
+
+__bxwm__ is built around a set of opinionated primitives:
+
+- Window Sizing & Placement
+  - New windows are opened at a golden ratio dimension, centered on the screen
+  - Windows can be moved and resized to
+    - centered half the width of the screen and full height
+    - right half of the screen and full height
+    - left half of the screen and full height
+    - maximized to full screen height and width, and,
+    - back to a small screen centered at a golden ratio dimension.
+
+- Stacking
+  - Windows are maintained in a stack
+  - The focus follows the stack order, allowing for rapid movement between the “top” and “bottom” windows.
+
+- Workspaces
+  - There are 10 distinct workspaces available to organize your environment.
+  - Windows can be moved between workspaces, and navigation is persistent.
+
+Window management commands via hotkeys are sent to __bxwm__ via __bxhkd__.
+
+To start __bxwm__, add the following line to your `~/.xinitrc`:
+
+```
+exec bxwm 2> ~/.local/var/log/bxwm.log
+```
+