hyprland-lua-migration

Hyprland is a popular Linux window manager, and version 0.55 changed the way its configuration files are written, switching from a custom format called hyprlang to real Lua code. That is a breaking change with no official guide from the Hyprland project itself, so this repository fills that gap. It is not a script you run, but a structured reference document meant to be read and used by an AI agent.

Specifically, this is an Agent Skill, a format made up of one main guide file and a folder of detailed reference documents, designed to be loaded by AI assistants that support this format, such as Pi. Once loaded, the assistant can use it to accurately convert an old style hyprland.conf file into the new hyprland.lua format, explain what changed, and help troubleshoot configs that broke during the upgrade.

The reference material is thorough. It covers core syntax and file structure, every configuration variable with notes on what is old, new, or removed, key bindings, every dispatcher command, window and layer rules, monitor and workspace settings, animations and gestures, and events and custom layouts. Each old construct is shown next to its new Lua equivalent, so nothing is left to guesswork.

The author built this by comparing the actual source code and documentation of Hyprland versions 0.54 and 0.55 directly, rather than guessing at behavior. This is aimed squarely at Hyprland users doing the version upgrade, and it is most useful when loaded into an AI assistant that understands the Agent Skills format, rather than read as plain documentation on its own.