chore: update html, md files

Browse Source
This commit is contained in:
retoor 2026-01-09 00:18:43 +01:00
parent f64aedc1fc
commit 90b460ddaa
5 changed files with 247 additions and 366 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

495
README.md
View File

@ -1,431 +1,194 @@
# DWN - Desktop Window Manager
Author: retoor <retoor@molodetz.nl>
DWN is a high-performance, X11-compliant window manager written in ANSI C. It combines the efficiency of tiling layouts with the usability of a full desktop environment, featuring integrated status bars, system tray support, and a robust notification system.
A lightweight, AI-enhanced window manager for Linux with tiling, floating, and fullscreen layouts.
## Project Vision
## Quick Start (Copy & Paste These Commands)
The Desktop Window Manager (DWN) is designed for users who seek a productive, tiling-first workflow without sacrificing modern desktop features. It adheres to EWMH and ICCCM standards, ensuring compatibility with contemporary applications while providing advanced automation capabilities through its built-in WebSocket API.
```bash
# 1. Install dependencies (enter your password when asked)
make deps
## Key Features
# 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
- XDG Autostart support (automatically starts nm-applet, blueman, etc.)
- 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
---
* **Hybrid Layout Management**: Seamlessly switch between Tiling (Master-Stack), Monocle, and Floating modes on a per-workspace basis.
* **Virtual Workspaces**: Supports 9 independent workspaces with persistent state and layout configurations.
* **Integrated Desktop Components**:
* **Status Panel**: Built-in top and bottom panels with workspace indicators, taskbars, and system clocks.
* **System Tray**: XEmbed-compliant systray implementation.
* **Notification Daemon**: Integrated D-Bus notification server support.
* **AI Integration**: Native support for LLM-assisted window management and semantic command execution.
* **Command Palette**: Intelligent prompt-based interface for window and system management.
* **Auto-Organization**: Context-aware window placement and workspace optimization.
* **Smart Notifications**: Intelligent filtering and prioritization based on application context.
* **Semantic Search**: Deep integration with Exa for enhanced application launching and web search.
* **Extensible API**: A real-time WebSocket interface for remote control and introspection.
## Installation
### Step 1: Install Dependencies
### Prerequisites
Run this command (works on Ubuntu, Debian, Fedora, and Arch):
DWN requires the following development libraries:
* `libX11`, `libXext`, `libXinerama`, `libXrandr`, `libXft`
* `fontconfig`
* `libdbus-1`
* `libcurl` (for AI features)
### Building
```bash
# Clone the repository
git clone https://github.com/your-repo/dwn.git
cd dwn
# Install dependencies (automated for apt/dnf/pacman)
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
# Compile the project
make
```
You should see "Build successful!" at the end.
### Running
### Step 3: Test (Recommended!)
Before installing, test DWN in a safe window:
To test DWN without affecting your current session, use the provided Xephyr-based runner:
```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
To install system-wide:
```bash
sudo make install
```
### Step 5: Use DWN
## AI-Assisted Management
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!
DWN differentiates itself through deep integration with Large Language Models (LLMs) via the OpenRouter API. This allows for semantic understanding of your workflow and proactive window management.
---
### Features
* **Natural Language Commands**: Control your workspace using plain English (e.g., "move all browser windows to workspace 3", "arrange my coding environment").
* **Intelligent Context**: The AI is aware of your active windows, workspace layouts, and historical usage patterns.
* **Workflow Optimization**: Proactive suggestions for layout changes based on your current activity (coding vs. browsing vs. communication).
* **Semantic App Launcher**: Find and launch applications based on intent rather than just binary names.
## Basic Controls
To use AI features, configure your API keys in `config.ini`:
```ini
[ai]
enabled = true
model = anthropic/claude-3-sonnet
openrouter_key = YOUR_API_KEY
exa_key = YOUR_EXA_KEY
```
### Essential Shortcuts (Memorize These!)
## WebSocket API
| 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** |
| `Super + Shift + D` | **Demo mode** (automated feature showcase) |
DWN exposes a powerful WebSocket API that allows external applications to monitor state and control the window manager programmatically.
### Workspaces
### Connectivity
* **Default Port**: `8777`
* **Endpoint**: `ws://localhost:8777/ws`
* **Protocol**: JSON-RPC style messages
| 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 |
The API is disabled by default. It can be enabled in the configuration file:
```ini
[api]
enabled = true
port = 8777
```
### Window Management
### API Commands
| Keys | What it does |
|------|--------------|
| `Alt + F9` | Toggle minimize/restore |
| `Alt + F10` | Toggle maximize |
| `Alt + F11` | Toggle fullscreen |
| `Super + F9` | Toggle floating mode |
| `Alt + Tab` | Cycle windows forward |
| `Alt + Shift + Tab` | Cycle windows backward |
All commands are sent as JSON objects containing a `command` field.
### Layout Control (Super key shortcuts)
#### 1. `get_status`
Retrieves the current state of the window manager.
* **Response**: Returns an object with version, current workspace ID, and total client count.
| 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 |
| `Super + Left` | Snap window to left half (50% width) |
| `Super + Right` | Snap window to right half (50% width) |
#### 2. `get_workspaces`
Lists all workspaces and their current configuration.
* **Response**: An array of workspace objects (ID, Name, Layout, Client Count).
### AI Features (Optional)
#### 3. `get_clients`
Lists all managed windows across all workspaces.
* **Response**: An array of client objects containing:
* `window`: X11 Window ID
* `title`: Window title
* `class`: Window class
* `workspace`: Workspace ID
* `geometry`: x, y, width, height
* `focused`: Boolean indicating focus state
| 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 |
#### 4. `switch_workspace`
Changes the active workspace.
* **Parameters**: `{"command": "switch_workspace", "workspace": <int>}`
### News Ticker
#### 5. `run_command`
Executes an arbitrary shell command.
* **Parameters**: `{"command": "run_command", "exec": "<string>"}`
The bottom panel displays a scrolling news ticker. Navigate articles with these shortcuts:
#### 6. `focus_client`
Focuses a specific window and switches to its workspace if necessary.
* **Parameters**: `{"command": "focus_client", "window": <long>}`
| Keys | What it does |
|------|--------------|
| `Super + Down` | Next news article |
| `Super + Up` | Previous news article |
| `Super + Return` | Open current article in browser |
### Example Usage (Python)
### Other Shortcuts
```python
import websocket
import json
| Keys | What it does |
|------|--------------|
| `Print` | Take screenshot (xfce4-screenshooter) |
ws = websocket.create_connection("ws://localhost:8777/ws")
---
# Switch to workspace 2
ws.send(json.dumps({
"command": "switch_workspace",
"workspace": 2
}))
## System Tray
# Get all clients
ws.send(json.dumps({"command": "get_clients"}))
result = ws.recv()
print(json.loads(result))
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.
ws.close()
```
### XEmbed System Tray (External Application Icons)
### Advanced API Examples
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:
The `scripts/api_examples/` directory contains several sophisticated applications leveraging the WebSocket API:
- **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.
### 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.
---
* **Window Picker (`window_picker_fzf.py`)**: A terminal-based window switcher using `fzf`. It allows for fuzzy-searching through all open windows across all workspaces and jumping to the selected one.
* **Web Remote (`web_remote.html`)**: A standalone, mobile-friendly HTML5 dashboard. Control your window manager from a tablet or phone on the same network.
* **Session Manager (`session_manager.py`)**: Save and restore your window layouts. Snapshots current open applications and their workspace assignments for easy restoration.
* **Auto-Manager (`listen.py`)**: A background service that monitors workspace occupancy and proactively suggests moving windows if a workspace becomes too crowded.
## Configuration
DWN can be customized by editing a config file.
DWN looks for a configuration file at `~/.config/dwn/config.ini`. If not found, it falls back to `/etc/dwn/config.ini`.
### Create Your Config
Refer to `config/config.example` for a documented template of all available options, including color schemes, keybindings, and autostart commands.
```bash
mkdir -p ~/.config/dwn
cp /etc/dwn/config.example ~/.config/dwn/config
```
## Development
### Edit Your Config
DWN is built with modularity in mind. Each major component is isolated in its own source file to facilitate easier debugging and feature additions.
Open `~/.config/dwn/config` in any text editor. Here are common changes:
### Key Components
* `src/main.c`: The core event loop and X11 event dispatcher.
* `src/client.c`: Window management logic (framing, focus, resizing).
* `src/layout.c`: Tiling and floating layout algorithms.
* `src/api.c`: WebSocket server and JSON command handler.
* `src/ai.c`: OpenRouter API integration and semantic logic.
**Change terminal:**
```ini
[general]
terminal = gnome-terminal
```
Options: `xfce4-terminal`, `gnome-terminal`, `konsole`, `alacritty`, `xterm`
### Coding Standards
* Strict adherence to ANSI C (C89/C90) for maximum compatibility.
* No external dependencies beyond standard X11 and networking libraries.
* Formatting is enforced via `clang-format`. Run `make format` before submitting patches.
**Change app launcher:**
```ini
[general]
launcher = rofi -show run
```
## Codebase Structure
**Change layout:**
```ini
[layout]
default = floating
```
Options: `tiling`, `floating`, `monocle`
**Change window gaps:**
```ini
[appearance]
gap = 10
border_width = 2
```
**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/
```
---
## 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 |
---
* `src/`: Core implementation logic.
* `include/`: Header files and internal API definitions.
* `config/`: Configuration templates.
* `scripts/`: Deployment and utility scripts.
* `site/`: Technical documentation and architecture overviews.
## 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/)
This project is licensed under the MIT License - see the `LICENSE` file for details.

12
site/ai-features.html
View File

@ -84,6 +84,18 @@
Find relevant content instantly.</p>
<p style="margin-top: 1rem;"><kbd>Super</kbd> + <kbd>Shift</kbd> + <kbd>E</kbd></p>
</div>
<div class="feature-card">
<div class="feature-icon">&#128221;</div>
<h3>Auto-Organization</h3>
<p>Context-aware window placement and workspace optimization
based on your current workflow.</p>
</div>
<div class="feature-card">
<div class="feature-icon">&#128276;</div>
<h3>Smart Notifications</h3>
<p>Intelligent filtering and prioritization of system notifications
using application context.</p>
</div>
</div>
<h2 id="openrouter" style="margin-top: 4rem;">Setting Up OpenRouter</h2>
<p style="color: var(--text-muted); margin-bottom: 1.5rem;">

64
site/documentation.html
View File

@ -62,6 +62,7 @@
<li>
<span class="section-title">Reference</span>
<ul>
<li><a href="#api">WebSocket API</a></li>
<li><a href="shortcuts.html">Keyboard Shortcuts</a></li>
<li><a href="configuration.html">Configuration</a></li>
<li><a href="ai-features.html">AI Features</a></li>
@ -340,6 +341,69 @@
the current article with <kbd>Super</kbd> + <kbd>Return</kbd>. Both panels can
be hidden in the configuration if you prefer a minimal setup.
</p>
<h2 id="api">WebSocket API</h2>
<p>
DWN exposes a real-time WebSocket API (default port <code>8777</code>) that allows for
complete programmatic control of the window manager.
</p>
<div class="card">
<h3>Connecting</h3>
<p>Endpoint: <code>ws://localhost:8777/ws</code></p>
<p>The API must be enabled in your configuration:</p>
<pre><code>[api]
enabled = true
port = 8777</code></pre>
</div>
<h3>Supported Commands</h3>
<div class="table-wrapper">
<table>
<thead>
<tr>
<th>Command</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>get_status</code></td>
<td>Get WM version and current workspace ID</td>
</tr>
<tr>
<td><code>get_workspaces</code></td>
<td>List all workspaces and their client counts</td>
</tr>
<tr>
<td><code>get_clients</code></td>
<td>Get details of all managed windows</td>
</tr>
<tr>
<td><code>switch_workspace</code></td>
<td>Change to a specific workspace ID</td>
</tr>
<tr>
<td><code>run_command</code></td>
<td>Execute a shell command</td>
</tr>
<tr>
<td><code>focus_client</code></td>
<td>Focus a specific window by ID</td>
</tr>
</tbody>
</table>
</div>
<h3>Advanced Examples</h3>
<p>
Check the <code>scripts/api_examples/</code> directory in the source tree for
sophisticated implementations:
</p>
<ul>
<li><strong>Window Picker</strong> (<code>window_picker_fzf.py</code>) - Fuzzy finder for windows.</li>
<li><strong>Session Manager</strong> (<code>session_manager.py</code>) - Save/restore window layouts.</li>
<li><strong>Web Remote</strong> (<code>web_remote.html</code>) - Browser-based dashboard.</li>
<li><strong>Auto-Manager</strong> (<code>listen.py</code>) - Proactive workspace optimization.</li>
</ul>
<h2>Next Steps</h2>
<p>Now that you know the basics, explore these topics:</p>
<ul>

30
site/features.html
View File

@ -291,6 +291,36 @@
</div>
</div>
</section>
<section class="section">
<div class="container">
<h2>Extensible API</h2>
<p style="color: var(--text-muted); max-width: 700px; margin-bottom: 2rem;">
DWN exposes a real-time WebSocket API that allows for complete programmatic
control and monitoring of your desktop environment.
</p>
<div class="features-grid">
<div class="card">
<h3>&#128161; Real-time Monitoring</h3>
<p>Subscribe to window manager events and state changes. Build custom dashboards,
status bars, or automation scripts.</p>
</div>
<div class="card">
<h3>&#127915; Remote Control</h3>
<p>Change workspaces, focus windows, and launch applications programmatically
from any language that supports WebSockets.</p>
</div>
<div class="card">
<h3>&#128187; Integration Ready</h3>
<p>Native support for JSON-RPC style commands makes it easy to integrate with
external tools, mobile apps, or web interfaces.</p>
</div>
</div>
<div class="alert alert-info" style="margin-top: 2rem;">
<p style="margin: 0;">Detailed API documentation and examples are available in the
<a href="documentation.html#api">Documentation section</a>.</p>
</div>
</div>
</section>
<section class="section section-alt">
<div class="container">
<h2>Standards Compliance</h2>

12
site/index.html
View File

@ -85,6 +85,12 @@
<p>Optional AI command palette and semantic web search. Control your desktop
with natural language and get intelligent suggestions.</p>
</div>
<div class="feature-card">
<div class="feature-icon">&#128172;</div>
<h3>Extensible API</h3>
<p>Real-time WebSocket interface for programmatic control. Build custom
dashboards, mobile remotes, and automated workflows.</p>
</div>
<div class="feature-card">
<div class="feature-icon">&#128276;</div>
<h3>Notification Daemon</h3>
@ -181,6 +187,12 @@ echo "exec dwn" >> ~/.xinitrc</code></pre>
</div>
<div class="screenshot-caption">AI-powered command palette for natural language control</div>
</div>
<div class="screenshot">
<div class="screenshot-placeholder">
[WebSocket API Dashboard]
</div>
<div class="screenshot-caption">Real-time WebSocket API for custom integrations</div>
</div>
</div>
</div>
</section>