2025-12-28 04:34:24 +01:00
# DWN - Desktop Window Manager
Author: retoor < retoor @ molodetz . nl >
A lightweight, AI-enhanced window manager for Linux with tiling, floating, and fullscreen layouts.
## Quick Start (Copy & Paste These Commands)
```bash
# 1. Install dependencies (enter your password when asked)
make deps
# 2. Build DWN
make
# 3. Test it (opens in a safe window - won't affect your desktop)
make run
```
That's it! Press `Super+Backspace` to exit the test window.
---
## What is DWN?
DWN is a **window manager** - the program that controls how windows look and behave on your screen. It replaces your current desktop environment (like GNOME, KDE, or XFCE) with a faster, keyboard-driven alternative.
**Features:**
- 3 window layouts: Tiling (windows don't overlap), Floating (like normal), Monocle (fullscreen)
- 9 virtual workspaces to organize your windows
- Built-in panels with clock, taskbar, and system tray
2025-12-28 09:26:53 +01:00
- XDG Autostart support (automatically starts nm-applet, blueman, etc.)
2025-12-28 04:34:24 +01:00
- WiFi network selector with dropdown menu (like XFCE)
- Audio volume indicator with scroll-to-adjust
- Desktop notifications
- Optional AI assistant (can launch apps by command!)
- Very fast and lightweight
---
## Installation
### Step 1: Install Dependencies
Run this command (works on Ubuntu, Debian, Fedora, and Arch):
```bash
make deps
```
This installs everything DWN needs. You'll need to enter your password.
**If `make deps` doesn't work**, install manually:
- Ubuntu/Debian: `sudo apt install build-essential pkg-config libx11-dev libxext-dev libxinerama-dev libxrandr-dev libdbus-1-dev libcurl4-openssl-dev xserver-xephyr dmenu network-manager alsa-utils`
- Fedora: `sudo dnf install gcc make pkg-config libX11-devel libXext-devel libXinerama-devel libXrandr-devel dbus-devel libcurl-devel xorg-x11-server-Xephyr dmenu NetworkManager alsa-utils`
- Arch: `sudo pacman -S base-devel pkg-config libx11 libxext libxinerama libxrandr dbus curl xorg-server-xephyr dmenu networkmanager alsa-utils`
### Step 2: Build
```bash
make
```
You should see "Build successful!" at the end.
### Step 3: Test (Recommended!)
Before installing, test DWN in a safe window:
```bash
make run
```
This opens DWN inside a window on your current desktop. You can try it out without changing anything. Press `Super+Backspace` to close it.
### Step 4: Install
```bash
sudo make install
```
### Step 5: Use DWN
1. Log out of your current session
2. At the login screen, click the **gear icon** (or session selector) near your username
3. Select ** "DWN"** from the list
4. Log in!
---
## Basic Controls
### Essential Shortcuts (Memorize These!)
| Keys | What it does |
|------|--------------|
| `Ctrl + Alt + T` | Open a terminal |
| `Super` or `Alt + F2` | Open app launcher |
| `Super + E` | Open file manager |
| `Super + B` | Open web browser |
| `Alt + Tab` | Switch between windows |
| `Alt + F4` | Close current window |
| `Super + Backspace` | **Exit DWN** (important!) |
| `Super + S` | **Show all shortcuts** |
| `Super + T` | **Start interactive tutorial** |
2025-12-28 09:26:53 +01:00
| `Super + Shift + D` | **Demo mode** (automated feature showcase) |
2025-12-28 04:34:24 +01:00
### Workspaces
| Keys | What it does |
|------|--------------|
| `Ctrl + Alt + Right` | Next workspace |
| `Ctrl + Alt + Left` | Previous workspace |
| `F1` to `F9` | Switch to workspace 1-9 |
| `Shift + F1` to `Shift + F9` | Move window to workspace 1-9 |
### Window Management
| Keys | What it does |
|------|--------------|
2025-12-28 09:26:53 +01:00
| `Alt + F9` | Toggle minimize/restore |
2025-12-28 04:34:24 +01:00
| `Alt + F10` | Toggle maximize |
| `Alt + F11` | Toggle fullscreen |
2025-12-28 09:26:53 +01:00
| `Super + F9` | Toggle floating mode |
2025-12-28 04:34:24 +01:00
| `Alt + Tab` | Cycle windows forward |
| `Alt + Shift + Tab` | Cycle windows backward |
### Layout Control (Super key shortcuts)
| Keys | What it does |
|------|--------------|
| `Super + Space` | Change layout mode (tiling → floating → monocle) |
| `Super + H` | Shrink main area |
| `Super + L` | Expand main area |
| `Super + I` | Add window to main area |
| `Super + D` | Remove window from main area |
2025-12-28 09:26:53 +01:00
| `Super + Left` | Snap window to left half (50% width) |
| `Super + Right` | Snap window to right half (50% width) |
2025-12-28 04:34:24 +01:00
### AI Features (Optional)
| Keys | What it does |
|------|--------------|
| `Super + A` | Show AI context info |
| `Super + Shift + A` | Ask AI to do something (e.g., "open firefox") |
| `Super + Shift + E` | Exa semantic web search |
### News Ticker
The bottom panel displays a scrolling news ticker. Navigate articles with these shortcuts:
| Keys | What it does |
|------|--------------|
| `Super + Down` | Next news article |
| `Super + Up` | Previous news article |
| `Super + Return` | Open current article in browser |
### Other Shortcuts
| Keys | What it does |
|------|--------------|
| `Print` | Take screenshot (xfce4-screenshooter) |
---
## System Tray
2025-12-28 09:26:53 +01:00
The top panel includes a system tray on the right side with support for external application icons plus built-in battery, audio, and WiFi indicators.
### XEmbed System Tray (External Application Icons)
DWN implements the freedesktop.org XEmbed System Tray protocol, allowing external applications to dock their status icons in the panel - just like XFCE, GNOME, or KDE. This means applications like:
- **Telegram** - Shows notification icon when messages arrive
- **nm-applet** - NetworkManager GUI applet
- **blueman-applet** - Bluetooth manager
- **pasystray** - PulseAudio volume control
- **udiskie** - USB device automounter
- **clipit/parcellite** - Clipboard managers
...will automatically appear in your system tray when launched.
Simply start any application with tray icon support and it will dock itself in the panel. Click on icons to interact with them - clicks are forwarded to the application.
2025-12-28 04:34:24 +01:00
### Battery Indicator
Shows battery percentage on laptops with color coding:
- **Green**: > 50%
- **Yellow**: 20-50%
- **Red**: < 20 %
- **Blue**: Charging
### WiFi Indicator
Located in the top-right corner of the panel, showing your current connection status.
| Action | What it does |
|--------|--------------|
| **Click** on WiFi icon | Open dropdown with available networks |
| **Click** on a network | Connect to that network |
| **Click** on connected network | Disconnect |
The dropdown shows:
- Available WiFi networks with signal strength
- `●` marker next to the currently connected network
- Networks are sorted and updated automatically
**Note:** Requires NetworkManager (`nmcli`) to be installed.
### Audio Indicator
Shows current volume level next to the WiFi indicator.
| Action | What it does |
|--------|--------------|
| **Left-click** | Toggle mute/unmute |
| **Scroll up** | Increase volume by 5% |
| **Scroll down** | Decrease volume by 5% |
**Note:** Requires ALSA utilities (`amixer`) to be installed.
---
## Configuration
DWN can be customized by editing a config file.
### Create Your Config
```bash
mkdir -p ~/.config/dwn
cp /etc/dwn/config.example ~/.config/dwn/config
```
### Edit Your Config
Open `~/.config/dwn/config` in any text editor. Here are common changes:
**Change terminal:**
```ini
[general]
terminal = gnome-terminal
```
Options: `xfce4-terminal` , `gnome-terminal` , `konsole` , `alacritty` , `xterm`
**Change app launcher:**
```ini
[general]
launcher = rofi -show run
```
**Change layout:**
```ini
[layout]
default = floating
```
Options: `tiling` , `floating` , `monocle`
**Change window gaps:**
```ini
[appearance]
gap = 10
border_width = 2
```
2025-12-28 09:26:53 +01:00
**Configure autostart:**
```ini
[autostart]
enabled = true
xdg_autostart = true
path = ~/.config/dwn/autostart.d
```
DWN automatically starts applications from XDG autostart directories:
- `/etc/xdg/autostart/` - System apps (nm-applet, blueman, etc.)
- `~/.config/autostart/` - User apps
- `~/.config/dwn/autostart.d/` - DWN-specific symlinks
To add custom autostart apps:
```bash
mkdir -p ~/.config/dwn/autostart.d
ln -s /usr/bin/telegram-desktop ~/.config/dwn/autostart.d/
```
2025-12-28 04:34:24 +01:00
---
## AI Features (Optional)
DWN has an AI assistant that can run commands for you. For example, you can press `Super+Shift+A` , type "open chrome", and it will launch Chrome.
### AI Command Setup (OpenRouter)
1. Go to [openrouter.ai ](https://openrouter.ai ) and create a free account
2. Get your API key
3. Add it to your shell config:
```bash
echo 'export OPENROUTER_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc
```
4. Make sure dmenu is installed: `sudo apt install dmenu`
### Exa Semantic Search Setup
1. Go to [dashboard.exa.ai ](https://dashboard.exa.ai/api-keys ) and create an account
2. Get your API key
3. Add it to your shell config:
```bash
echo 'export EXA_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc
```
### Usage
- Press `Super + A` to see AI context info about your current task
- Press `Super + Shift + A` to ask the AI to do something:
- "open firefox" - launches Firefox
- "run terminal" - opens a terminal
- "what time is it" - answers your question
- Press `Super + Shift + E` to search the web semantically:
- Type a question like "how to configure nginx"
- Select a result to open in browser
---
## Troubleshooting
### "make: command not found"
Install build tools:
```bash
sudo apt install build-essential
```
### "X11 libraries not found" or build errors
Install dependencies:
```bash
make deps
```
### Can't find DWN at login screen
Make sure you ran `sudo make install` , then:
```bash
ls /usr/share/xsessions/dwn.desktop
```
If missing:
```bash
sudo cp scripts/dwn.desktop /usr/share/xsessions/
```
### Terminal shortcut doesn't work
Install the default terminal:
```bash
sudo apt install xfce4-terminal
```
Or change terminal in config (see Configuration section).
### Screen is blank after login
DWN started but there's nothing to show. Press `Ctrl+Alt+T` to open a terminal.
### How do I get back to my normal desktop?
1. Press `Super+Backspace` to exit DWN
2. At login screen, select your previous desktop (GNOME, KDE, etc.)
### AI says "dmenu not found"
```bash
sudo apt install dmenu
```
### WiFi indicator not working
Make sure NetworkManager is installed and running:
```bash
sudo apt install network-manager
sudo systemctl enable --now NetworkManager
```
### Audio indicator not working
Make sure ALSA utilities are installed:
```bash
sudo apt install alsa-utils
```
---
## Uninstall
```bash
sudo make uninstall
```
Then select a different desktop at the login screen.
---
## All Make Commands
| Command | What it does |
|---------|--------------|
| `make help` | Show all commands |
| `make deps` | Install dependencies |
| `make` | Build DWN |
| `make debug` | Build with debug symbols |
| `make run` | Test in a window |
| `make install` | Install system-wide |
| `make uninstall` | Remove from system |
| `make clean` | Delete build files |
| `make format` | Format source code |
| `make check` | Run static analysis |
---
## License
MIT License - do whatever you want with it.
## Credits
- Inspired by [dwm ](https://dwm.suckless.org/ ) and [XFCE ](https://xfce.org/ )
- AI powered by [OpenRouter ](https://openrouter.ai/ )
