|
# DWN - Desktop Window Manager
|
|
|
|
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.
|
|
|
|
## Project Vision
|
|
|
|
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.
|
|
|
|
## Key Features
|
|
|
|
* **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
|
|
|
|
### Prerequisites
|
|
|
|
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
|
|
|
|
# Compile the project
|
|
make
|
|
```
|
|
|
|
### Running
|
|
|
|
To test DWN without affecting your current session, use the provided Xephyr-based runner:
|
|
|
|
```bash
|
|
make run
|
|
```
|
|
|
|
To install system-wide:
|
|
|
|
```bash
|
|
sudo make install
|
|
```
|
|
|
|
## AI-Assisted Management
|
|
|
|
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.
|
|
|
|
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
|
|
```
|
|
|
|
## WebSocket API
|
|
|
|
DWN exposes a powerful WebSocket API that allows external applications to monitor state and control the window manager programmatically.
|
|
|
|
### Connectivity
|
|
* **Default Port**: `8777`
|
|
* **Endpoint**: `ws://localhost:8777/ws`
|
|
* **Protocol**: JSON-RPC style messages
|
|
|
|
The API is disabled by default. It can be enabled in the configuration file:
|
|
```ini
|
|
[api]
|
|
enabled = true
|
|
port = 8777
|
|
```
|
|
|
|
### API Commands
|
|
|
|
All commands are sent as JSON objects containing a `command` field.
|
|
|
|
#### 1. `get_status`
|
|
Retrieves the current state of the window manager.
|
|
* **Response**: Returns an object with version, current workspace ID, and total client count.
|
|
|
|
#### 2. `get_workspaces`
|
|
Lists all workspaces and their current configuration.
|
|
* **Response**: An array of workspace objects (ID, Name, Layout, Client Count).
|
|
|
|
#### 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
|
|
|
|
#### 4. `switch_workspace`
|
|
Changes the active workspace.
|
|
* **Parameters**: `{"command": "switch_workspace", "workspace": <int>}`
|
|
|
|
#### 5. `run_command`
|
|
Executes an arbitrary shell command.
|
|
* **Parameters**: `{"command": "run_command", "exec": "<string>"}`
|
|
|
|
#### 6. `focus_client`
|
|
Focuses a specific window and switches to its workspace if necessary.
|
|
* **Parameters**: `{"command": "focus_client", "window": <long>}`
|
|
|
|
### Example Usage (Python)
|
|
|
|
```python
|
|
import websocket
|
|
import json
|
|
|
|
ws = websocket.create_connection("ws://localhost:8777/ws")
|
|
|
|
# Switch to workspace 2
|
|
ws.send(json.dumps({
|
|
"command": "switch_workspace",
|
|
"workspace": 2
|
|
}))
|
|
|
|
# Get all clients
|
|
ws.send(json.dumps({"command": "get_clients"}))
|
|
result = ws.recv()
|
|
print(json.loads(result))
|
|
|
|
ws.close()
|
|
```
|
|
|
|
### Advanced API Examples
|
|
|
|
The `scripts/api_examples/` directory contains several sophisticated applications leveraging the WebSocket API:
|
|
|
|
* **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 looks for a configuration file at `~/.config/dwn/config.ini`. If not found, it falls back to `/etc/dwn/config.ini`.
|
|
|
|
Refer to `config/config.example` for a documented template of all available options, including color schemes, keybindings, and autostart commands.
|
|
|
|
## Development
|
|
|
|
DWN is built with modularity in mind. Each major component is isolated in its own source file to facilitate easier debugging and feature additions.
|
|
|
|
### 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.
|
|
|
|
### 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.
|
|
|
|
## Codebase Structure
|
|
|
|
* `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
|
|
|
|
This project is licensed under the MIT License - see the `LICENSE` file for details. |