All source listed below is under MIT license if no LICENSE file stating different is available.

DWN - Desktop Window Manager

A production-ready X11 window manager written in ANSI C with EWMH/ICCCM protocol compliance, tiling-first workflow, integrated desktop components, and optional AI integration via OpenRouter API.

Design Philosophy

DWN prioritizes a seamless, distraction-free desktop experience:

Zero borders and gaps: Windows tile edge-to-edge without visual separation
Minimal chrome: 28px title bars provide window controls without excess decoration
Tiling-first: Master-stack layout as the default, with floating and monocle modes available
Keyboard-driven: Comprehensive shortcuts for all operations
Modular architecture: Single-responsibility modules with strict encapsulation
ANSI C: Maximum portability and minimal dependencies

Features

Window Management

Layout Modes

Tiling: Master-stack layout with configurable master ratio (0.1-0.9) and master window count
Floating: Traditional overlapping windows with free positioning
Monocle: Single maximized window per workspace

Composable Window Snapping

Super+Arrow keys snap windows to half-screen positions
Double-press extends to full width/height
Combinations create quarter-screen positions (e.g., Super+Left then Super+Up = top-left quarter)

Directional Resizing

Resize windows from any edge or corner
Respects layout bounds and snap constraints

Window States

Fullscreen (Alt+F11): Covers entire screen including panels
Maximized (Alt+F10): Fills usable area with title bar
Minimized (Alt+F9): Hidden from view
Floating (Super+F9): Exempt from tiling layout
Sticky: Visible on all workspaces
Urgent: Demands attention with taskbar highlight

Workspace System

9 independent virtual workspaces (F1-F9)
Per-workspace layout persistence
MRU (Most Recently Used) focus stack per workspace
Alt-Tab cycles through MRU order
Shift+F1-F9 moves focused window to target workspace
Ctrl+Alt+Left/Right navigates adjacent workspaces

Panels

Top Panel

Workspace indicators with active/inactive/urgent states
Taskbar with window buttons
System tray with XEmbed protocol support
Battery indicator (multi-battery support)
Volume control with slider
Top memory process display
Top CPU process display
Key press counter
Mouse distance traveled
Clock

Bottom Panel

News ticker with scrolling headlines
Configurable visibility

System Tray

XEmbed Protocol

Acquires _NET_SYSTEM_TRAY_S0 selection
Docks external application icons (nm-applet, blueman, Telegram, etc.)
Forwards click events to icon windows
Automatic cleanup on application close

Built-in Widgets

Battery: Percentage display, charging indicator, multi-battery support
Volume: Click for slider, scroll to adjust, right-click to mute
Process monitors: Rotating display of top CPU/memory consumers

Ambient Glow Effects

Visual feedback system with phase-offset animations:

Panel background subtle color cycling
Workspace indicator glow
Taskbar button highlighting
Clock and statistics display
Window title text glow on focus
Configurable animation speed

Activity Tracking

Key press counter: Total keypresses displayed in panel
Mouse distance: Cumulative mouse movement in pixels
XInput2 integration: Raw event monitoring for accurate tracking

Focus Transitions

Animated color transitions on window focus changes
Taskbar button color interpolation
Title bar glow animations
Bold font rendering for Alt-Tab selection

Notification System

D-Bus implementation of org.freedesktop.Notifications:

Receives notifications from all applications
Stacked display with timeout management
Urgency levels: low, normal, critical
Click to dismiss

News Ticker

Fetches headlines from configured sources
Smooth pixel-based scrolling animation
Super+Return opens current article in browser
Automatic refresh interval
Sentiment indicators (positive/negative/neutral)

AI Integration

Command Palette (Super+Shift+A)

Natural language command execution
OpenRouter API with configurable model selection
Context-aware responses based on current workspace

Context Analysis (Super+A)

Task type detection (coding, browsing, communication)
Window and application analysis
Intelligent suggestions

Exa Semantic Search (Super+Shift+E)

Meaning-based web search
Results displayed in dmenu/rofi
Select to open in browser

Screenshot and OCR

Screenshot API

Fullscreen capture
Active window capture
Area selection capture
Async capture with callbacks
Base64 encoding for API transmission
PNG output

OCR API

Tesseract-based text extraction
Multi-language support
Confidence scoring
Async processing

WebSocket API

Programmatic control on port 8777:

Command	Description
`get_status`	Window manager state
`get_workspaces`	Workspace information
`get_clients`	All managed windows
`switch_workspace`	Change active workspace
`focus_client`	Focus specific window
`run_command`	Execute shell command
`screenshot`	Capture screen
`ocr`	Extract text from image

Automation

XDG Autostart

Scans /etc/xdg/autostart/ and ~/.config/autostart/
Parses .desktop files
Custom autostart directory support

Service Manager

Background process management
Automatic restart on failure

Interactive Features

Tutorial (Super+T)

Step-by-step keyboard shortcut training
Waits for correct input
Progressive difficulty

Demo Mode (Super+Shift+D)

Automated feature showcase
Configurable timing
Covers all major features

Shortcuts Help (Super+S)

Quick reference overlay
All keyboard bindings displayed

Installation

Dependencies

Required libraries (via pkg-config):

X11, Xext, Xinerama, Xrandr, Xft, Xi
fontconfig
libdbus-1
libcurl
libpng
tesseract (optional, for OCR)

Build

make deps      # Auto-install dependencies (apt/dnf/pacman)
make           # Build with -O2 optimization
make install   # Install to /usr/local/bin (PREFIX configurable)

Testing

make run       # Launch in nested Xephyr window

Build Targets

Target	Description
`make`	Release build with optimization
`make debug`	Debug build with -g -DDEBUG
`make clean`	Remove build artifacts
`make format`	Run clang-format
`make check`	Run cppcheck static analysis

Configuration

Configuration file: ~/.config/dwn/config (INI format)

General

[general]
terminal = xfce4-terminal
launcher = dmenu_run
file_manager = thunar
focus_mode = click              # click or follow
focus_follow_delay = 100        # 0-1000ms
decorations = true

Appearance

[appearance]
border_width = 0                # 0-50px
title_height = 28               # 0-100px
panel_height = 32               # 0-100px
gap = 0                         # 0-100px
font = fixed

Layout

[layout]
default = tiling                # tiling, floating, monocle
master_ratio = 0.55             # 0.1-0.9
master_count = 1                # 1-10

Panels

[panels]
top = true
bottom = true

Colors

[colors]
panel_bg = #080808
panel_fg = #00ff00
workspace_active = #ff00ff
workspace_inactive = #222222
workspace_urgent = #ff0000
title_focused_bg = #00ffff
title_focused_fg = #000000
title_unfocused_bg = #111111
title_unfocused_fg = #444444
border_focused = #00ff00
border_unfocused = #000000
notification_bg = #111111
notification_fg = #00ffff

AI

[ai]
model = google/gemini-2.0-flash-exp:free
openrouter_api_key = sk-or-v1-your-key
exa_api_key = your-exa-key

Environment variables:

export OPENROUTER_API_KEY=sk-or-v1-your-key
export EXA_API_KEY=your-exa-key

API keys:

OpenRouter: https://openrouter.ai/keys
Exa: https://dashboard.exa.ai/api-keys

Autostart

[autostart]
enabled = true
xdg_autostart = true
path = ~/.config/dwn/autostart.d

API

[api]
enabled = true
port = 8777

Demo

[demo]
step_delay = 4000               # 1000-30000ms
ai_timeout = 15000              # 5000-60000ms
window_timeout = 5000           # 1000-30000ms

Keyboard Shortcuts

Application Launchers

Shortcut	Action
`Ctrl+Alt+T`	Terminal
`Super` / `Alt+F2`	Application launcher
`Super+E`	File manager
`Super+B`	Web browser
`Print`	Screenshot

Window Management

Shortcut	Action
`Alt+F4`	Close window
`Alt+Tab`	Next window (MRU order)
`Alt+Shift+Tab`	Previous window
`Alt+F9`	Toggle minimize
`Alt+F10`	Toggle maximize
`Alt+F11`	Toggle fullscreen
`Super+F9`	Toggle floating

Shortcut	Action
`F1` - `F9`	Switch to workspace 1-9
`Shift+F1` - `Shift+F9`	Move window to workspace 1-9
`Ctrl+Alt+Right`	Next workspace
`Ctrl+Alt+Left`	Previous workspace

Layout Control

Shortcut	Action
`Super+Space`	Cycle layout mode
`Super+H`	Shrink master area
`Super+L`	Expand master area
`Super+I`	Increase master count
`Super+D`	Decrease master count / Show desktop

Window Snapping

Shortcut	Action
`Super+Left`	Snap left (50% or 100%)
`Super+Right`	Snap right (50% or 100%)
`Super+Up`	Snap top (50% or 100%)
`Super+Down`	Snap bottom (50% or 100%)

AI Features

Shortcut	Action
`Super+A`	Context analysis
`Super+Shift+A`	Command palette
`Super+Shift+E`	Exa semantic search

News and Help

Shortcut	Action
`Super+Return`	Open current article
`Super+S`	Shortcuts help
`Super+T`	Interactive tutorial
`Super+Shift+D`	Toggle demo mode
`Super+Backspace`	Quit DWN

Architecture

Module Structure

Module	Responsibility
main.c	X11 initialization, event loop, signal handling
client.c	Window management, focus, frame creation
workspace.c	Virtual desktop management, MRU stacks
layout.c	Tiling, floating, monocle algorithms
decorations.c	Title bars, borders, glow animations
panel.c	Top/bottom panel rendering, widgets
systray.c	XEmbed system tray, battery/volume widgets
notifications.c	D-Bus notification daemon
atoms.c	EWMH/ICCCM atom management
keys.c	Keyboard shortcut handling
config.c	INI configuration parser
ai.c	OpenRouter API, Exa search integration
news.c	News ticker with scrolling animation
screenshot.c	Screen capture API
ocr.c	Tesseract text extraction
autostart.c	XDG autostart implementation
services.c	Background service management
demo.c	Automated feature demonstration
api.c	WebSocket server
util.c	Logging, memory, string utilities, glow effects

Design Patterns

Encapsulation

Opaque pointer types hide internal structures
Header exposes only public API
Implementation details remain private

Error Handling

Status code return values
Output parameters for results
Enum-based error codes

Resource Management

Goto cleanup pattern for multi-resource functions
Every allocation has corresponding free
XGrabServer/XUngrabServer for atomic X11 operations

Event Architecture

Select-based multiplexed I/O
60fps animation loop with 16ms timeout
Async request queues for AI/screenshot/OCR

Naming Conventions

Module prefix for functions: client_focus(), workspace_switch()
Snake_case for functions and variables
CamelCase for types and structs

Key Constants

Constant	Value
MAX_CLIENTS	256
MAX_WORKSPACES	9
MAX_MONITORS	8
MAX_NOTIFICATIONS	32
MAX_KEYBINDINGS	64

WebSocket API Examples

Python

import websocket
import json

ws = websocket.create_connection("ws://localhost:8777/ws")

ws.send(json.dumps({"command": "get_clients"}))
clients = json.loads(ws.recv())

ws.send(json.dumps({"command": "switch_workspace", "workspace": 3}))

ws.send(json.dumps({"command": "focus_client", "window": 12345678}))

ws.close()

Response Format

{
  "status": "ok",
  "data": {
    "clients": [
      {
        "window": 12345678,
        "title": "Firefox",
        "class": "firefox",
        "workspace": 1,
        "x": 0, "y": 32,
        "width": 960, "height": 540,
        "focused": true
      }
    ]
  }
}

Project Structure

dwn/
├── src/           # Implementation files
├── include/       # Header files
├── config/        # Configuration templates
├── scripts/       # Utility scripts
├── examples/      # API usage examples
├── site/          # Documentation website
└── build/         # Build artifacts

License

MIT License - see LICENSE file.

bin
build
config
examples
include
manual
site
src
LICENSE
Makefile
README.md

DWN - Desktop Window Manager

Design Philosophy

Features

Window Management

Workspace System

Panels

System Tray

Ambient Glow Effects

Activity Tracking

Focus Transitions

Notification System

News Ticker

AI Integration

Screenshot and OCR

WebSocket API

Automation

Interactive Features

Installation

Dependencies

Build

Testing

Build Targets

Configuration

General

Appearance

Layout

Panels

Colors

AI

Autostart

API

Demo

Keyboard Shortcuts

Application Launchers

Window Management

Workspace Navigation

Layout Control

Window Snapping

AI Features

News and Help

Architecture

Module Structure

Design Patterns

Key Constants

WebSocket API Examples

Python

Response Format

Project Structure

License