HyprPilot

Programmatic control of the Hyprland Wayland compositor — for AI agents and humans. A typed Rust IPC client, a long-running daemon with undo & snapshots, a CLI, and a stdio MCP server, plus input synthesis and screen capture + OCR.

RustHyprlandWayland MCP serverAI agentsCLIv1.0.0

The crates

• hyprpilot-core — async Hyprland IPC client (control + event sockets), typed queries and dispatchers.
• hyprpilot-daemon — JSON-RPC over a Unix socket, with a reversible-operation undo stack and snapshots.
• hyprpilot-cli — the hyprpilot binary: window/workspace ops, queries, daemon control, undo.
• hyprpilot-mcp — stdio MCP server exposing Hyprland control to MCP hosts (Claude Desktop, Claude Code) as typed tools with capability profiles and a dry-run default.
• hyprpilot-input — input synthesis (typing, key chords, mouse) via wtype, ydotool, and sendshortcut.
• hyprpilot-vision — screen capture via grim and OCR via tesseract.

Install (Arch / AUR)

yay -S hyprpilot-mcp      # or: paru -S hyprpilot-mcp

Installs the hyprpilot, hyprpilot-daemon, and hyprpilot-mcp binaries.

Quick start

cargo build --release

# Direct queries (no daemon needed)
./target/release/hyprpilot query active-window
./target/release/hyprpilot win cycle
./target/release/hyprpilot ws switch 2

# Daemon-backed undo
./target/release/hyprpilot-daemon &
./target/release/hyprpilot --use-daemon ws send +1
./target/release/hyprpilot undo

Why it exists

AI agents that drive a desktop need a typed, reversible, dry-run-safe way to query and mutate window-manager state. HyprPilot gives them that for Hyprland, while staying useful as a plain CLI for humans. Full docs, MCP setup, and capability profiles are in the README on GitHub.