Skip to main content
Glama

🐎 brand

The Hyprland agent-control plane that refuses to lie about focus.

build Hyprland license MCP security

Why should I care? Every agent-control tool for Hyprland dispatches a focus command and trusts the ok. On Hyprland 0.56.x the IPC Lua API silently broke (hl is boolean true β€” hyprctl eval "return type(hl.dsp)" errors), so those oks were fiction and agents typed into the wrong window. brand races three independent actuation paths concurrently and only declares victory when the compositor itself reports the right window focused. A bare ok that didn't move focus is a loss β€” retried, aggregated, and reported honestly.

Rebirth of the archived Hypr-Agent-Portal β€” forked, re-themed, and actively maintained by toxicwind. The original author archived it believing CUA made it redundant; we disagree: nobody else verifies focus.


  • 🎯 Hyper-race focus β€” plugin dispatcher, wlrctl, and legacy hyprctl raced concurrently; first strictly-verified win takes it

  • 🧬 Native hyprpm plugin β€” dispatchers run inside the compositor, immune to the IPC-Lua breakage: manage, pointer, keyboard, screenshot, session, panic, guard, approval

  • πŸ›‘οΈ Stale-target refusal β€” windows are identified by address@pid@starttime; a recycled address can never steal focus

  • πŸ” Honest errors β€” VerificationFailed / StaleTarget taxonomy instead of silent success

  • ⌨️ AT-SPI input path β€” accessibility-native typing, no ydotool daemon

  • πŸ”’ Security policy β€” capability allowlists, panic mode, privacy denylist for screenshots, human input preempts the agent instantly

  • πŸ§ͺ Composable testing β€” BRAND_MOCK_COMPOSITOR=1 and BRAND_DRY_RUN=1 let you develop the whole stack with no compositor at all

Diagram

flowchart LR
    A[MCP client] --> B[brand-mcp.py]
    B --> C{focus_window_race}
    C -->|A| D["brand:manage focus<br/>(native plugin)"]
    C -->|B| E["wlrctl<br/>(external)"]
    C -->|C| F["hyprctl focuswindow<br/>(legacy)"]
    D --> G[Hyprland compositor]
    E --> G
    F --> G
    G --> H{"hyprctl -j activewindow<br/>== requested address?"}
    H -->|yes| I[βœ… verified win]
    H -->|no| J[❌ path loses,<br/>errors aggregated]

Related MCP server: cvision-mcp

Quick start

hyprpm add https://github.com/toxicwind/brand && hyprpm enable brand && hyprpm reload
python3 mcp/brand-mcp.py   # stdio MCP server β€” point your agent at it
# hyprland.conf β€” capabilities are opt-in
plugin {
  brand {
    allow_pointer = 1
    allow_keyboard = 1
    allow_screenshot = 1
    allow_session = 1
  }
}

Architecture

Layer

Lives in

Job

MCP server

mcp/brand-mcp.py

Tool surface: window_action, type_into, screenshots, OCR

Hyper-race

mcp/brand_focus_race.py

Races actuation paths, strict verification only

Window mgmt

mcp/hypr_management.py

Stale-target refusal, VerificationFailed taxonomy

Native plugin

src/plugin/ (libbrand.so)

In-compositor dispatchers; bypasses broken IPC Lua

Input

AT-SPI

Focused-editable text insertion, no daemon

The key insight: the plugin never touches the IPC Lua state, so the 0.56.x hl-boolean breakage doesn't apply to it. The Python side treats the plugin as the preferred path but never the only path β€” if the plugin is absent or disabled, the race still runs on wlrctl + legacy hyprctl, verified the same way.

Config

Plugin block (hyprland.conf, hyprlang or Lua under plugin.brand):

Key

Default

Purpose

allow_pointer

1

Background pointer dispatchers

allow_keyboard

1

Background keyboard dispatchers

allow_screenshot

1

Compositor screenshot dispatchers

allow_session

1

Workspace session dispatchers

show_indicator / indicator_timeout_ms

1 / 30000

On-screen agent-activity indicator

cancel_on_human_input

1

Physical input preempts the agent

privacy_class_denylist

KeePassXC,1Password

Classes hidden from screenshots

Environment (local dev / CI β€” see .env.example):

Variable

Purpose

BRAND_DISABLE_PLUGIN=1

Skip the native plugin path; race wlrctl + legacy only

BRAND_DRY_RUN=1

Log every actuation, change nothing

BRAND_MOCK_COMPOSITOR=1

Talk to the in-repo mock instead of a real compositor

Dev

# plugin
cmake -S . -B build && cmake --build build        # -> build/libbrand.so

# tests β€” self-contained runners, no pytest needed (mock compositor, no Hyprland)
python3 tests/mcp_smoke.py mcp/brand-mcp.py
for t in tests/*.py; do
  case "$t" in tests/mcp_smoke.py|tests/mock_compositor.py) continue;; esac
  python3 "$t"
done

License + security

GPL-3.0 β€” see LICENSE. Fork lineage: full upstream history preserved (upstream remote β†’ gfhdhytghd/Hypr-Agent-Portal).

Security model: SECURITY.md. Short version β€” the plugin is a deliberately narrow gateway: callers can't name arbitrary Hyprland dispatchers, every window target is address@pid@starttime qualified, the session lock blocks all management, and one brand:panic freezes everything.

Available Tools

45 tools
activate_menu_itemA
Destructive

Activate a global app-menu item from get_app_state. Uses DBusMenu/GMenu when the app exposes a menu model; this is independent of AT-SPI menu roles.

Inputs: app (required), menu_index (required), confirmation_token.

audit_replayC
Destructive

Preflight the redacted audit journal and optionally replay only entries that remain safe after identity and policy validation.

Inputs: execute, allow_clipboard, confirmation_token, max_record_age_seconds.

clickB
Destructive

Click a visible element by index, accessible name/text, or screenshot/window-relative coordinates. Element clicks use the native pointer path so the visible agent cursor overlay appears.

Inputs: app (required), x, y, name, +7 more.

click_markB
Destructive

Click one bound Set-of-Marks id after live identity, geometry, and screenshot-hash validation.

Inputs: app (required), mark_id (required), marks_id (required), click_count, +2 more.

click_textB
Destructive

Click OCR text from an opaque current ocr_id. The server revalidates screenshot hash, process identity, and geometry before input.

Inputs: app (required), text (required), ocr_id (required), nth, +5 more.

computerbrandB
Destructive

brand compatibility tool for Hyprland background Computer Use, including browser/Chromium control through Hyprland. Prefer app plus get_app_state/screenshot coordinates; target/x/y global coordinates are only the low-level fallback. Do not use Browser MCP when the user explicitly asks for brand. Do not use the obsolete hyprcum namespace.

Inputs: action (required), x, y, dx, +84 more.

double_clickC
Destructive

Compatibility alias for a double left click.

Inputs: app (required), x, y, name, +5 more.

dragB
Destructive

Drag from one screenshot/window-relative coordinate to another.

Inputs: app (required), to_x, to_y, from_x, +6 more.

get_app_stateA
Read-onlyIdempotent

Get a target app/window screenshot, accessibility tree, and uiHints. Call this before action tools, then use element_index or screenshot/window-relative coordinates. uiHints separates AT-SPI menu entries from tab/ribbon/toolbar controls; do not substitute a same-named menu for a requested tab.

Inputs: app (required).

get_cursor_positionB
Read-onlyIdempotent

Return the current cursor position in monitor, screenshot, or window-relative coordinates.

Inputs: app, source, include_global.

get_marksC
Read-onlyIdempotent

Render a non-destructive numbered Set-of-Marks overlay for a bound target screenshot and return an opaque marks_id mapping.

Inputs: app (required), zoom, scale, format, +7 more.

get_screenshotD
Read-onlyIdempotent

Compatibility alias for screenshot.

Inputs: app, zoom, scale, format, +7 more.

hoverB
Destructive

Compatibility alias: move the background pointer to an element or coordinate without clicking.

Inputs: app (required), x, y, name, +5 more.

keyA
Destructive

Compatibility alias for press_key. Accepts key, keys, modifiers, keycode, or text.

Inputs: app (required), key, keys, text, +4 more.

launch_appA
Destructive

Open or launch an app through Hyprland and return a window selector. By default this reuses an already running matching window; set reuse_existing=false only when the user explicitly asks for a new instance/window. For browser tasks, use this instead of Browser MCP only when an app launch/open is requested.

Inputs: app, url, args, command, +4 more.

left_clickB
Destructive

Compatibility alias for click with the left button.

Inputs: app (required), x, y, name, +5 more.

left_click_dragC
Destructive

Compatibility alias for drag using start_coordinate and coordinate.

Inputs: app (required), coordinate (required), start_coordinate (required), duration, +2 more.

list_appsA
Read-onlyIdempotent

List running Hyprland apps/windows available to brand. Start here before choosing a target app unless the user explicitly asks to launch a new app/window.

Inputs: no named parameters.

list_windowsA
Read-onlyIdempotent

Compatibility alias for list_apps.

Inputs: no named parameters.

list_workspacesB
Read-onlyIdempotent

List Hyprland workspaces; special workspaces are included by default and explicitly identified by Hyprland.

Inputs: include_special.

manage_windowC
Destructive

Targeted, verified Hyprland window management: focus/close/move/resize/minimize/maximize/fullscreen/floating/pin/move_to_workspace.

Inputs: action (required), x, y, app, +10 more.

manage_workspaceC
Destructive

Verified Hyprland workspace switch/create-or-activate/rename and targeted window move. special: selectors retain Hyprland special-workspace semantics.

Inputs: action (required), workspace (required), app, follow, +4 more.

middle_clickB
Destructive

Compatibility alias for click with the middle button.

Inputs: app (required), x, y, name, +5 more.

move_mouseC
Destructive

Compatibility alias for hover.

Inputs: app (required), x, y, name, +5 more.

ocrA
Read-onlyIdempotent

Run a local OCR backend on a newly captured, privacy-filtered target screenshot. Returns normalized confidence 0..1, screenshot pixel boxes, and an opaque short-lived ocr_id.

Inputs: app (required), region, backend, timeout, +3 more.

open_appB
Destructive

Compatibility alias for launch_app.

Inputs: app, url, args, command, +4 more.

panicA
Destructive

Immediately cancel active background operations. panic latches writes off; cancel is one-shot; resume clears the latch; status is read-only.

Inputs: mode, confirmation_token.

paste_textA
Destructive

Paste text through the clipboard into the target app. Prefer this for multiline, tabular, CSV/TSV, Unicode-heavy, or long text because it is much faster than key-by-key typing.

Inputs: app (required), text (required), restore_delay, prefer_related, +2 more.

perform_secondary_actionC
Destructive

Invoke a secondary AT-SPI action exposed by an element.

Inputs: app (required), action (required), element_index (required), confirmation_token.

press_keyB
Destructive

Press a key or key-combination, using xdotool-style syntax such as ctrl+v, Return, alt+left, or super+c.

Inputs: app (required), key, keys, repeat, +3 more.

read_app_stateC
Read-onlyIdempotent

Compatibility alias for get_app_state.

Inputs: app (required).

request_confirmationA
Destructive

Create a pending challenge bound to an exact high-risk call. A person must approve it from an independent local TTY before it can authorize the action.

Inputs: arguments (required), tool_name (required), confirmation_token.

right_clickC
Destructive

Compatibility alias for click with the right button.

Inputs: app (required), x, y, name, +5 more.

screenshotB
Read-onlyIdempotent

Capture an unoccluded screenshot for an app/window, or the visible compositor if no app is passed. Prefer app over low-level target.

Inputs: app, zoom, scale, format, +7 more.

scrollC
Destructive

Scroll an element or coordinate in a direction by pages.

Inputs: app (required), direction (required), x, y, +7 more.

security_statusA
Read-onlyIdempotent

Return the active desktop-control security policy and readiness diagnostics without exposing secrets.

Inputs: no named parameters.

sequenceB
Destructive

Run an ordered action sequence. Every step re-enters the ordinary single-tool policy, confirmation, confinement, lease, and audit gateway; nested sequences are rejected.

Inputs: steps (required), dry_run, max_steps, stop_on_error, +1 more.

set_valueC
Destructive

Set the value of a settable accessibility element.

Inputs: app (required), value (required), element_index (required), confirmation_token.

triple_clickC
Destructive

Compatibility alias for a triple left click.

Inputs: app (required), x, y, name, +5 more.

typeC
Destructive

Compatibility alias for type_text.

Inputs: app (required), text (required), method, confirmation_token.

type_intoC
Destructive

Atomically resolve and verify an editable target, focus it, refresh state, then input text using auto/AT-SPI/paste/keys.

Inputs: app (required), text (required), nth, match, +11 more.

type_textA
Destructive

Type literal text into the target app. Use paste_text for multiline, tabular, CSV/TSV, Unicode-heavy, or long text. method=auto prefers a focused AT-SPI editable control, then uses isolated background key/paste input; method=atspi explicitly requests accessibility text insertion.

Inputs: app (required), text (required), method, confirmation_token.

waitC
Read-onlyIdempotent

Compatibility alias: wait for a short duration.

Inputs: duration.

wait_for_closeB
Read-onlyIdempotent

Wait for a target window/dialog to close. If related_to is provided, return the surviving related/root app state.

Inputs: app, target, timeout, related_to.

wait_for_windowA
Read-onlyIdempotent

Wait for a Hyprland window or same-process related popup/dialog to appear, then return its app state. Use after actions expected to open dialogs or new windows.

Inputs: app, class, title, timeout, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.7/5.0

    Scored across 45 tools

    Disambiguation2/5

    Roughly a third of the surface is explicit duplicate aliases (open_app=launch_app, read_app_state=get_app_state, get_screenshot=screenshot, list_windows=list_apps, key=press_key, left/right/middle/double/triple_click=click, hover/move_mouse, type=type_text, left_click_drag=drag), so an agent frequently has two or more tools that do the identical thing. Overlaps also exist among non-alias tools: type_text vs type_into vs paste_text vs set_value, and screenshot vs get_app_state. The 'Compatibility alias for X' phrasing helps, but boundaries remain murky.

    Naming Consistency3/5

    All names are snake_case with no camelCase mixing, which is good, but verb conventions are inconsistent: verb_noun (get_app_state, list_apps, click_text, manage_window) coexists with bare verbs (click, scroll, drag, hover, panic, wait, sequence) and bare nouns (computer, ocr, screenshot). The name 'computer' for a compatibility tool is especially uninformative and breaks any pattern.

    Tool Count2/5

    45 tools is far beyond a comfortable set and is inflated by ~14 pure aliases that add no capability. Even discounting aliases, the 30 real tools cover a lot of ground, but the alias bloat makes the surface heavy and hard to scan.

    Completeness4/5

    For a Hyprland desktop-control agent the lifecycle is well covered: discovery (list_apps, list_windows), state capture (get_app_state, screenshot, ocr, get_marks), input (click, type_text, paste_text, press_key, scroll, drag, set_value), window/workspace management, and safety (security_status, request_confirmation, panic, audit_replay, sequence). Minor gaps only, e.g. no explicit clipboard read/copy-back or multi-monitor enumeration beyond cursor coordinates.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to control a Hyprland Wayland desktop by listing windows, capturing screenshots, and sending input to a dedicated agent workspace without disrupting the user's screen.
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables background window capture and input automation without moving the cursor or stealing focus, working across Windows, Linux X11, and Wayland systems.
      6
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables a constrained subagent to perform foreground GUI actions on Hyprlandβ€”observing, focusing windows, clicking, typing, scrolling, dragging, and managing the clipboardβ€”under per-action approval with lease, audit log, and kill-switch gating.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to control Hyprland desktops via MCP, including pointer/keyboard input, screenshots, launching apps, and natural-language window targeting using a local decision model.
      14
      1
      MIT