API Reference

// Request
{"command": "get_clients"}

// Response
{
    "status": "ok",
    "clients": [
        {
            "window": 12345678,
            "title": "Window Title",
            "class": "window-class",
            "workspace": 0,
            "x": 0,
            "y": 32,
            "width": 960,
            "height": 540,
            "focused": true,
            "floating": false,
            "fullscreen": false,
            "maximized": false,
            "minimized": false
        }
    ]
}

// Request - find by title (substring match)
{"command": "find_clients", "title": "Firefox"}

// Request - find by class
{"command": "find_clients", "class": "terminal"}

// Request - find by workspace
{"command": "find_clients", "workspace": 2}

// Request - combine filters
{"command": "find_clients", "class": "code", "workspace": 0}

// Response
{
    "status": "ok",
    "clients": [...]
}

// Request
{"command": "get_focused_client"}

// Response
{
    "status": "ok",
    "client": {
        "window": 12345678,
        "title": "...",
        "class": "...",
        ...
    }
}

// Request
{"command": "focus_client", "window": 12345678}

// Response (returns current status)
{
    "status": "ok",
    "version": "2.0.0",
    "current_workspace": 0,
    "client_count": 5
}

// Request
{"command": "close_client", "window": 12345678}

// Response
{"status": "ok"}

// Request
{"command": "kill_client", "window": 12345678}

// Response
{"status": "ok"}

// Request
{
    "command": "move_client",
    "window": 12345678,
    "x": 100,
    "y": 100
}

// Response
{"status": "ok"}

// Request
{
    "command": "resize_client",
    "window": 12345678,
    "width": 800,
    "height": 600
}

// Response
{"status": "ok"}

{"command": "minimize_client", "window": 12345678}

{"command": "restore_client", "window": 12345678}

// Toggle maximize
{"command": "maximize_client", "window": 12345678}

// Set explicit state
{"command": "maximize_client", "window": 12345678, "state": true}

// Toggle fullscreen
{"command": "fullscreen_client", "window": 12345678}

// Set explicit state
{"command": "fullscreen_client", "window": 12345678, "state": true}

// Toggle floating
{"command": "float_client", "window": 12345678}

// Set explicit state
{"command": "float_client", "window": 12345678, "state": true}

{"command": "raise_client", "window": 12345678}

{"command": "lower_client", "window": 12345678}

// Request
{"command": "get_workspaces"}

// Response
{
    "status": "ok",
    "workspaces": [
        {
            "id": 0,
            "name": "1",
            "layout": 0,
            "client_count": 3
        },
        {
            "id": 1,
            "name": "2",
            "layout": 0,
            "client_count": 0
        }
        // ... workspaces 2-8
    ]
}

// Request
{"command": "switch_workspace", "workspace": 2}

// Response
{
    "status": "ok",
    "version": "2.0.0",
    "current_workspace": 2,
    "client_count": 5
}

{
    "command": "move_client_to_workspace",
    "window": 12345678,
    "workspace": 3
}

{"command": "switch_workspace_next"}

// Response
{
    "status": "ok",
    "workspace": 1,
    "workspace_name": "2"
}

{"command": "switch_workspace_prev"}

// Set layout by name ("tiling", "floating", or "monocle")
{"command": "set_layout", "layout": "floating"}

// Set layout by number (0=tiling, 1=floating, 2=monocle)
{"command": "set_layout", "layout": 1}

// Optionally specify workspace (defaults to current)
{"command": "set_layout", "layout": "monocle", "workspace": 2}

// Cycle current workspace
{"command": "cycle_layout"}

// Cycle specific workspace
{"command": "cycle_layout", "workspace": 3}

// Set on current workspace
{"command": "set_master_ratio", "ratio": 0.6}

// Set on specific workspace
{"command": "set_master_ratio", "ratio": 0.55, "workspace": 2}

// Response
{
    "status": "ok",
    "workspace": 0,
    "master_ratio": 0.6
}

// Increase master area by 5%
{"command": "adjust_master_ratio", "delta": 0.05}

// Decrease master area by 5%
{"command": "adjust_master_ratio", "delta": -0.05}

{"command": "set_master_count", "count": 2}

// Response
{
    "status": "ok",
    "workspace": 0,
    "master_count": 2
}

// Add one window to master
{"command": "adjust_master_count", "delta": 1}

// Remove one window from master
{"command": "adjust_master_count", "delta": -1}

{"command": "focus_next"}

// Response
{
    "status": "ok",
    "focused_window": 12345678,
    "focused_title": "Firefox"
}

{"command": "focus_prev"}

{"command": "focus_master"}

// Snap focused window left
{"command": "snap_client", "direction": "left"}

// Snap specific window
{"command": "snap_client", "window": 12345678, "direction": "right"}

// Directions: left, right, up, down
// Snapping is composable: left then up = top-left corner

// Response
{
    "status": "ok",
    "window": 12345678,
    "snap": {
        "horizontal": 1,
        "vertical": 0
    }
}

// By keysym name (X11 keysym names)
{"command": "key_press", "keysym": "a"}
{"command": "key_press", "keysym": "Return"}
{"command": "key_press", "keysym": "Tab"}
{"command": "key_press", "keysym": "Escape"}
{"command": "key_press", "keysym": "F1"}
{"command": "key_press", "keysym": "Control_L"}

// By keycode (hardware keycode)
{"command": "key_press", "keycode": 38}

{"command": "key_release", "keysym": "a"}
{"command": "key_release", "keycode": 38}

// Simple key tap
{"command": "key_tap", "keysym": "a"}

// With modifiers (modifier keysym names)
{"command": "key_tap", "keysym": "c", "modifiers": ["Control_L"]}
{"command": "key_tap", "keysym": "t", "modifiers": ["Control_L", "Alt_L"]}
{"command": "key_tap", "keysym": "s", "modifiers": ["Control_L", "Shift_L"]}

// Special keys
{"command": "key_tap", "keysym": "Return"}
{"command": "key_tap", "keysym": "Tab"}
{"command": "key_tap", "keysym": "Escape"}
{"command": "key_tap", "keysym": "F1"}

{"command": "key_type", "text": "Hello, World!"}

{"command": "mouse_move", "x": 500, "y": 300}

{"command": "mouse_move_relative", "dx": 10, "dy": -5}

// Left click at current position
{"command": "mouse_click", "button": 1}

// Right click at specific position (moves mouse first)
{"command": "mouse_click", "button": 3, "x": 100, "y": 200}

{"command": "mouse_press", "button": 1}

{"command": "mouse_release", "button": 1}

// Scroll up (amount 1-100, default 1)
{"command": "mouse_scroll", "direction": "up", "amount": 3}

// Scroll down
{"command": "mouse_scroll", "direction": "down", "amount": 3}

// Request
{"command": "get_mouse_position"}

// Response
{
    "status": "ok",
    "x": 500,
    "y": 300,
    "window_x": 100,
    "window_y": 50,
    "window": 12345678
}

// Async (default) - returns when capture completes
{"command": "screenshot", "mode": "fullscreen"}

// Synchronous - blocks until complete
{"command": "screenshot", "mode": "fullscreen", "async": false}

// Request
{"command": "screenshot", "mode": "fullscreen"}

// Response
{
    "status": "ok",
    "format": "png",
    "encoding": "base64",
    "width": 1920,
    "height": 1080,
    "data": "iVBORw0KGgoAAAANSUhEUg..."
}

{"command": "screenshot", "mode": "active"}

{"command": "screenshot", "mode": "window", "window": 12345678}

{
    "command": "screenshot",
    "mode": "area",
    "x": 100,
    "y": 100,
    "width": 400,
    "height": 300
}

// Async (default)
{"command": "ocr", "image": "...", "language": "eng"}

// Synchronous
{"command": "ocr", "image": "...", "language": "eng", "async": false}

// Request
{
    "command": "ocr",
    "image": "iVBORw0KGgoAAAANSUhEUg...",  // base64 PNG
    "language": "eng"                        // optional, default "eng"
}

// Response
{
    "status": "ok",
    "text": "Extracted text from image...",
    "confidence": 0.95
}

// Request
{
    "command": "notify",
    "summary": "Hello!",
    "body": "This is a notification message",
    "app_name": "My App",
    "timeout": 5000
}

// Response
{
    "status": "ok",
    "notification_id": 1
}

{"command": "close_notification", "id": 1}

{"command": "get_notifications"}

// Response
{
    "status": "ok",
    "notifications": [
        {
            "id": 1,
            "app_name": "My App",
            "summary": "Hello!",
            "body": "This is a notification",
            "timeout": 5000,
            "urgency": 1
        }
    ]
}

{"command": "get_battery_state"}

// Response
{
    "status": "ok",
    "battery": {
        "present": true,
        "charging": false,
        "percentage": 75,
        "time_remaining": 180
    }
}

{"command": "get_audio_state"}

// Response
{
    "status": "ok",
    "volume": 50,
    "muted": false
}

{"command": "set_audio_volume", "volume": 75}

// Response
{
    "status": "ok",
    "volume": 75,
    "muted": false
}

{"command": "toggle_audio_mute"}

// Response
{
    "status": "ok",
    "muted": true,
    "volume": 75
}

{"command": "get_wifi_state"}

// Response
{
    "status": "ok",
    "enabled": true,
    "connected": true,
    "ssid": "MyNetwork",
    "signal_strength": 80
}

{"command": "get_panel_state"}

// Response
{
    "status": "ok",
    "top_panel": {
        "enabled": true,
        "visible": true,
        "x": 0,
        "y": 0,
        "width": 1920,
        "height": 32
    },
    "bottom_panel": {
        "enabled": true,
        "visible": true,
        "x": 0,
        "y": 1048,
        "width": 1920,
        "height": 32
    }
}

{"command": "show_panel", "panel": "top"}
{"command": "show_panel", "panel": "bottom"}

{"command": "hide_panel", "panel": "top"}

{"command": "toggle_panel", "panel": "bottom"}

{"command": "ai_is_available"}

// Response
{
    "status": "ok",
    "available": true,
    "model": "google/gemini-2.0-flash-exp:free"
}

// Request
{
    "command": "ai_command",
    "prompt": "What windows are open?",
    "async": true
}

// Response (when complete)
{
    "status": "ok",
    "response": "You have 3 windows open: Firefox, Terminal, and VS Code..."
}

{"command": "exa_is_available"}

// Response
{
    "status": "ok",
    "available": true
}

// Request
{
    "command": "exa_search",
    "query": "how to configure nginx reverse proxy",
    "async": true
}

// Response
{
    "status": "ok",
    "results": [
        {
            "title": "NGINX Reverse Proxy Configuration",
            "url": "https://example.com/nginx-guide",
            "snippet": "Learn how to configure NGINX as a reverse proxy...",
            "score": 0.95
        }
    ]
}

{"command": "get_news"}

// Response
{
    "status": "ok",
    "current_article": 0,
    "article_count": 10,
    "fetching": false,
    "has_error": false,
    "articles": [
        {
            "title": "Breaking News...",
            "content": "Article content...",
            "link": "https://example.com/news/1",
            "author": "John Doe",
            "sentiment": 0,
            "sentiment_score": 0.5
        }
    ]
}

{"command": "news_next"}

// Response
{
    "status": "ok",
    "current_article": 1,
    "title": "Next article title..."
}

{"command": "news_prev"}

{"command": "news_open"}

// Response
{
    "status": "ok",
    "link": "https://example.com/news/1"
}

{"command": "start_demo"}

{"command": "stop_demo"}

{"command": "get_demo_state"}

// Response
{
    "status": "ok",
    "active": true,
    "phase": 2,
    "phase_name": "DEMO_WORKSPACES",
    "step": 3
}

{"command": "start_tutorial"}

{"command": "stop_tutorial"}

{"command": "get_tutorial_state"}

// Response
{
    "status": "ok",
    "active": true
}

// Get specific key
{"command": "get_config", "key": "terminal"}

// Response
{
    "status": "ok",
    "value": "xfce4-terminal"
}

// Get all config
{"command": "get_config"}

// Response
{
    "status": "ok",
    "config": {
        "terminal": "xfce4-terminal",
        "launcher": "dmenu_run",
        "focus_mode": "click",
        "border_width": 0,
        "panel_height": 32,
        "gap": 0,
        "ai_enabled": true,
        "fade_speed": 0.5,
        "fade_intensity": 1.0
        ...
    }
}

{"command": "reload_config"}

// Response
{
    "status": "ok"
}

{"command": "get_keybindings"}

// Response
{
    "status": "ok",
    "keybindings": [
        {
            "key": "t",
            "modifiers": "ctrl+alt",
            "description": "Open terminal"
        },
        {
            "key": "F4",
            "modifiers": "alt",
            "description": "Close focused window"
        }
        ...
    ]
}

// Request
{"command": "list_events"}

// Response
{
    "status": "ok",
    "events": [
        "window_created",
        "window_destroyed",
        "window_focused",
        "window_unfocused",
        "window_moved",
        "window_resized",
        "window_minimized",
        "window_restored",
        "window_maximized",
        "window_unmaximized",
        "window_fullscreen",
        "window_unfullscreen",
        "window_floating",
        "window_unfloating",
        "window_title_changed",
        "window_raised",
        "window_lowered",
        "workspace_switched",
        "workspace_window_added",
        "workspace_window_removed",
        "workspace_layout_changed",
        "workspace_master_ratio_changed",
        "workspace_master_count_changed",
        "workspace_arranged",
        "layout_changed",
        "key_pressed",
        "key_released",
        "shortcut_triggered",
        "mouse_moved",
        "mouse_button_pressed",
        "mouse_button_released",
        "drag_started",
        "drag_ended",
        "show_desktop_toggled",
        "notification_shown",
        "notification_closed"
    ]
}

// Subscribe to specific events
{"command": "subscribe", "events": ["window_focused", "window_created"]}

// Subscribe to all events
{"command": "subscribe", "all": true}

// Response
{
    "status": "ok",
    "subscribed": ["window_focused", "window_created"]
}

// Unsubscribe from specific events
{"command": "unsubscribe", "events": ["window_focused"]}

// Unsubscribe from all events
{"command": "unsubscribe", "all": true}

// Response
{"status": "ok"}

// Window focus event
{
    "type": "event",
    "event": "window_focused",
    "data": {
        "window": 12345678,
        "title": "Firefox",
        "previous_window": 87654321
    }
}

// Window moved event
{
    "type": "event",
    "event": "window_moved",
    "data": {
        "window": 12345678,
        "old_x": 0,
        "old_y": 32,
        "new_x": 100,
        "new_y": 100
    }
}

// Workspace switched event
{
    "type": "event",
    "event": "workspace_switched",
    "data": {
        "old_workspace": 0,
        "new_workspace": 2
    }
}

// Keyboard shortcut triggered
{
    "type": "event",
    "event": "shortcut_triggered",
    "data": {
        "name": "Return",
        "description": "Open terminal"
    }
}

// Notification shown
{
    "type": "event",
    "event": "notification_shown",
    "data": {
        "id": 1,
        "summary": "New Message",
        "body": "You have a new message"
    }
}

// Fade speed changed
{
    "type": "event",
    "event": "fade_speed_changed",
    "data": {
        "old_speed": 0.5,
        "new_speed": 1.0
    }
}

// Fade intensity changed
{
    "type": "event",
    "event": "fade_intensity_changed",
    "data": {
        "old_intensity": 1.0,
        "new_intensity": 0.8
    }
}

// Request
{"command": "get_status"}

// Response
{
    "status": "ok",
    "version": "2.0.0",
    "current_workspace": 0,
    "client_count": 5
}

// Request
{"command": "get_screen_info"}

// Response
{
    "status": "ok",
    "screen_width": 1920,
    "screen_height": 1080,
    "screen": 0,
    "monitor_count": 1,
    "monitors": [
        {
            "index": 0,
            "x": 0,
            "y": 0,
            "width": 1920,
            "height": 1080,
            "primary": true
        }
    ],
    "usable_area": {
        "x": 0,
        "y": 32,
        "width": 1920,
        "height": 1048
    }
}

// Request
{"command": "run_command", "exec": "firefox"}

// Response
{"status": "launched"}

// Toggle
{"command": "show_desktop"}

// Set explicit state
{"command": "show_desktop", "state": true}

// Response
{
    "status": "ok",
    "desktop_shown": true
}

// Request
{"command": "get_fade_settings"}

// Response
{
    "status": "ok",
    "fade_speed": 0.5,
    "fade_intensity": 1.0
}

// Request
{"command": "set_fade_speed", "speed": 1.5}

// Response
{
    "status": "ok",
    "fade_speed": 1.5
}

// Request
{"command": "set_fade_intensity", "intensity": 0.8}

// Response
{
    "status": "ok",
    "fade_intensity": 0.8
}

{
    "status": "error",
    "message": "Window not found"
}

{
    "status": "error",
    "message": "Invalid parameter: workspace must be 0-8"
}

{
    "status": "error",
    "message": "Unknown command: invalid_command"
}