dwn/README.md

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