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

# 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:

make run

To install system-wide:

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:

[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:

[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)

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.