docs: add comprehensive readme with installation, features, and usage guide

Browse Source
This commit is contained in:
retoor 2025-12-28 04:34:24 +01:00
parent 9182d9931e
commit a6b9fa3469
1 changed files with 392 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

392
README.md Normal file
View File

@ -0,0 +1,392 @@
# 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
- 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** |
### 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 |
|------|--------------|
| `Super + F9` | Toggle floating mode |
| `Alt + F10` | Toggle maximize |
| `Alt + F11` | Toggle fullscreen |
| `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 |
### 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
The top panel includes a system tray on the right side with battery, audio, and WiFi indicators.
### 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
```
---
## 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/)