🐎 brand

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

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: astra-linux-agent

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

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

Environment (local dev / CI — see .env.example):

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.