GO — Healthy across the board

• Last commit today
• 30+ active contributors
• BSD-3-Clause licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 50% of recent commits

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

Hyprland is a completely independent, GPU-accelerated dynamic tiling Wayland compositor written in C++ that provides a modern Linux desktop with advanced visual effects (gradient borders, blur, animations, shadows) without relying on wlroots, libweston, or other external compositor libraries. It solves the problem of wanting a highly customizable, visually polished tiling window manager on Wayland while maintaining bleeding-edge feature velocity and plugin extensibility. Monolithic C++ application compiled via CMake. Core logic resides in src/ (inferred from CMakeLists.txt), configuration examples in example/ (hyprland.lua, hyprland.desktop.in, layouts/), debug utilities in debug-tools/, and documentation in docs/. GPU rendering uses custom GLSL shaders (51K LOC), with Lua scripting for layouts (30K LOC) and shell-based build/deployment automation.

Linux power users and enthusiasts who want a modern, visually rich tiling window manager; system administrators and embedded developers integrating a custom Wayland compositor; plugin developers extending compositor functionality via Hyprland's plugin SDK; contributors to the compositing ecosystem seeking a readable, actively-developed codebase.

Hyprland is actively developed and production-ready. The repository shows strong CI/CD automation (workflows in .github/workflows/ for nix-ci, release, security checks), comprehensive code quality tooling (.clang-format, .clang-tidy), and appears to have significant community engagement (pull request and issue templates indicate active maintenance). The 5M+ lines of C++ and established example configurations suggest stability, though as a relatively independent project (not backed by a large organization) it carries inherent maintenance risk.

Primary risk is single-organization dependency: Hyprland is '100% independent' by design, meaning security and feature vulnerabilities rest on the maintainer(s)' shoulders with no fallback to wlroots or mutter. The large C++ codebase (5M LOC) without visible test suite in the file list raises concerns about regression coverage. Breaking changes may occur during rapid development; the bleeding-edge philosophy prioritizes new features over stability guarantees.

Active development on plugin infrastructure, Wayland protocol compliance, and visual effects. The presence of .github/workflows/nix-update-inputs.yml, translation-ai-check.yml, and security-checks.yml indicates ongoing modernization. Man page updates (man-update.yaml) and release automation suggest regular version cycles.

git clone https://github.com/hyprwm/Hyprland.git
cd Hyprland
make all  # or cmake-based build per Makefile
# Install following docs/install or example/hyprland.desktop.in

Detailed setup in docs/ISSUE_GUIDELINES.md and the Quick Start wiki link.

Daily commands:

# Development build
make clean && make all
# Run as nested Wayland session (in X11 or another Wayland compositor)
HYPRLAND_LOG_WLR=1 ./build/bin/hyprland
# Or install and run as display server
# See example/hyprland.service for systemd integration

• CMakeLists.txt — Root build configuration defining all compilation targets, dependencies, and flags for the Wayland compositor—every contributor must understand the build system.
• hyprctl/src/main.cpp — Entry point for hyprctl IPC command interface; essential for understanding how external tools communicate with the compositor.
• hyprpm/src/main.cpp — Entry point for the plugin manager; critical for understanding plugin lifecycle, loading, and manifest handling.
• hyprpm/src/core/PluginManager.hpp — Core plugin system abstraction; defines how plugins are discovered, loaded, and managed at runtime.
• .clang-format — Code style definition enforced across the codebase; every contributor must adhere to this formatting standard.
• flake.nix — Nix package definition and development environment configuration; required for reproducible builds and contributions.
• VERSION — Single source of truth for release versioning; critical for version management and reproducibility.

Add a new hyprctl command

1. Define the command enum value in the protocol constants (hyprctl/src/Strings.hpp)
2. Implement the command handler in the main command router (hyprctl/src/main.cpp)
3. Add socket communication logic to send request to daemon (hyprpm/src/core/HyprlandSocket.cpp)
4. Update usage documentation in CLI help text (hyprctl/hyprctl.usage)

Add a new plugin hook/capability

1. Define hook interface in PluginManager header (hyprpm/src/core/PluginManager.hpp)
2. Implement hook invocation logic in manager implementation (hyprpm/src/core/PluginManager.cpp)
3. Add hook metadata to plugin manifest schema (hyprpm/src/core/Manifest.hpp)
4. Document hook in plugin development guide (docs/ISSUE_GUIDELINES.md)

Add a new test case for compositor behavior

1. Create new test client following naming convention (e.g., feature-name.cpp) (hyprtester/clients/)
2. Include test client in CMake build definition (hyprtester/CMakeLists.txt)
3. Use Wayland protocol stubs and socket communication (hyprpm/src/core/HyprlandSocket.hpp)

Modify plugin persistence or state tracking

1. Update data schema and serialization format (hyprpm/src/core/DataState.hpp)
2. Implement save/load logic for new state fields (hyprpm/src/core/DataState.cpp)
3. Ensure state is properly initialized in plugin manager (hyprpm/src/core/PluginManager.cpp)
4. Update version field if migration logic is required (VERSION)

• Wayland (as substrate, not implementation) — Modern display protocol; Hyprland is a 100% independent Wayland compositor, not built on wlroots, libweston, or KWin—enabling full customization and lightweight architecture.
• Unix sockets (AF_UNIX) for IPC — Low-latency, privilege-safe local communication between hyprctl CLI and Hyprland daemon; no network exposure.
• Dynamic library loading (dlopen/dlsym) — Plugin system allows runtime extension without recompilation; plugins are .so files loaded via PluginManager.
• CMake build system — Cross-platform build generation; integrates Nix flakes and supports layered dependency management.
• C++ (modern, possibly C++17+) — Performance-critical compositor work; RAII for resource safety; strong type system for plugin API contracts.

• 100% independent implementation vs. wlroots/libweston reuse

  • Why: Maximum control over features (bezier animations, tearing, advanced rendering) and code clarity
  • Consequence: Higher maintenance burden; all Wayland protocol negotiation implemented in-house; requires deeper Wayland protocol expertise.

• Plugin system via dynamic .so loading vs. static compilation

  • Why: Runtime extensibility and faster iteration; users can install plugins without recompiling Hyprland
  • Consequence: Increased stability risk (rogue plugins can crash compositor); requires ABI stability guarantees across versions.

• IPC via plain sockets + JSON vs. structured RPC framework

  • Why: Simplicity; CLI tools and scripts can easily invoke hyprctl; no heavy message serialization overhead
  • Consequence: Manual protocol versioning; less

Build environment: Requires full Wayland development stack (libwayland, wayland-protocols, libxkbcommon, etc.); CMake is strict about compiler flags (see .clang-tidy). Nix ecosystem heavy: .github/workflows/nix-*.yml suggests reproducible builds via Nix; non-Nix developers may struggle with dependency resolution. IPC socket path: hyprctl communicates via Wayland socket; ensure XDG_RUNTIME_DIR is set. Lua config reload: Config changes trigger instant reload but may not persist state; understand the difference between reload and restart. No wlroots = custom everything: Protocol implementations are hand-rolled; compatibility issues with non-standard Wayland clients are possible. GLSL shader compilation: GPU-specific optimizations; shader errors fail silently on some drivers—check logs via HYPRLAND_LOG_WLR.

• Wayland Compositor Architecture — Hyprland is a complete compositor, not a window manager; understanding the Wayland protocol, seat/pointer/keyboard abstractions, and double-buffering is essential to any core modification.
• GPU Rendering with OpenGL/GLSL — Visual effects (blur, gradients, shadows, animations) are implemented in GLSL shaders (51K LOC); shader understanding is required for graphics tweaks or debugging render artifacts.
• Dynamic Tiling Algorithm — Hyprland's core feature is dynamic window tiling with multiple layout engines (columns, master/stack); understanding layout state management and window tree traversal is critical for workspace/layout changes.
• Lua Scripting Integration — Layouts and user configuration are Lua-based (30K LOC Lua); contributing layout features or plugin infrastructure requires Lua API bindings and embedding knowledge.
• Socket-based IPC (hyprctl) — Hyprland's control protocol is message-based over Unix domain sockets; understanding command serialization and message dispatch is essential for CLI tooling and external integrations.
• Bezier Curve Animation — Custom bezier implementations drive smooth animations; understanding curve interpolation and timing functions affects animation behavior tuning and new effect development.
• CMake Build System Customization — Complex dependency resolution and compiler flags in CMakeLists.txt; modifying build targets, linking strategies, or compiler options requires CMake expertise.

• swaywm/sway — i3-like tiling Wayland compositor using wlroots; directly referenced in README as inspiration for 'the overkill way'
• riverwm/river — Minimal dynamic tiling Wayland compositor in Zig; alternative to Hyprland with similar goals but different language and philosophy
• hyprwm/Hypr — Companion repository in the Hyprwm organization; likely plugin ecosystem or toolkit for Hyprland
• wayland/wayland — Core Wayland protocol library; essential dependency and reference for understanding Hyprland's protocol implementations
• xkbcommon/libxkbcommon — Keyboard handling library used by Hyprland for XKB keymap processing and global keybind management

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add hyprctl command integration tests

The hyprctl directory exists with usage documentation (hyprctl/hyprctl.usage) and shell completions, but there are no automated tests validating command parsing, IPC communication, or output formatting. Given that hyprctl is a critical user-facing tool for controlling Hyprland via IPC, adding integration tests would catch regressions and improve reliability. Tests could validate command execution, argument parsing, and response formats.

• [ ] Create tests/hyprctl/ directory structure
• [ ] Add test cases in hyprctl/src/ for command parsing (reference hyprctl/src/Strings.hpp and hyprctl/src/helpers/)
• [ ] Implement IPC mock/stub in tests to validate command responses without full compositor
• [ ] Integrate tests into ci.yaml workflow to run on PRs

Add Lua layout engine unit tests

The example/layouts/ directory contains four Lua layout implementations (columns.lua, grid.lua, manual.lua, spiral.lua) that are core to Hyprland's functionality, but there are no tests validating layout logic, correctness, or edge cases. Adding tests would ensure layout algorithms handle window placement correctly and prevent regressions when the Lua API changes.

• [ ] Create tests/lua_layouts/ with test harness for Lua environment
• [ ] Add unit tests for each layout in example/layouts/ (validate window positioning, edge cases, empty workspaces)
• [ ] Mock Hyprland Lua API calls (window dimensions, workspace boundaries)
• [ ] Integrate into ci.yaml to run layout tests on every PR

Add missing man page source documentation for hyprctl subcommands

docs/hyprctl.1.rst exists but the .github/workflows/man-update.yaml workflow suggests man pages are generated or updated. However, there's no comprehensive structured documentation mapping hyprctl subcommands (from hyprctl/hyprctl.usage) to their RST documentation. This creates a gap between the usage file and rendered man pages, making maintenance harder.

• [ ] Parse hyprctl/hyprctl.usage to extract all subcommands and options
• [ ] Add detailed RST sections in docs/hyprctl.1.rst for each subcommand with examples
• [ ] Create a validation script in .github/workflows/ to ensure usage file and RST docs stay in sync
• [ ] Add CI check to prevent man page updates from being merged without corresponding docs/ changes

• Add missing test coverage for core layout algorithms in src/layouts/ (none detected in file list); write C++ unit tests using a framework like Catch2 or Google Test, then hook into ci.yaml.
• Expand example/hyprland.lua with commented sections for every major feature (animations, rules, keybinds, monitors); cross-reference each section with docs/Hyprland.1.rst to ensure docs/config parity and fill documentation gaps.
• Create a shell script in debug-tools/ that generates flamegraph.sh output with symbols properly resolved for the Hyprland binary; integrate into Makefile as a debug target and document in CONTRIBUTING (missing in file list).

Hyprland demonstrates reasonable security awareness with an established security policy and CI/CD workflows for security checks. However, the security posture is weakened by an incomplete disclosure policy, lack of LTS support, and unclear dependency management. The plugin system requires additional security hardening. The codebase shows no obvious injection vulnerabilities, hardcoded secrets, or exposed credentials in the analyzed file structure, but a more detailed source code review would be needed for comprehensive assessment. The use of Wayland and Rust components (indicated by compositor nature) provides some inherent memory safety advantages over X11-based alternatives.

• Medium · Incomplete Security Policy Documentation — SECURITY.md. The SECURITY.md file appears to be truncated at the end, cutting off critical information about how to report security issues. This incomplete documentation could lead to security researchers not knowing the proper disclosure process. Fix: Complete the SECURITY.md file with full instructions for private security disclosure, including contact methods, response timeframe expectations, and acknowledgment policy.
• Low · No LTS Support for Security Updates — SECURITY.md. The security policy explicitly states that only the most recent release is supported with no LTS versions. This means users on older versions may be running vulnerable code with no official support path. Fix: Consider maintaining security patches for at least 2-3 previous major releases, or provide clear upgrade guidance for users unable to immediately update.
• Low · Missing Dependency Management Documentation — Repository root, CMakeLists.txt. The provided file structure shows no visible package manager files (package.json, requirements.txt, Cargo.toml, etc.) or detailed dependency documentation. While CMakeLists.txt exists, external dependencies are not clearly itemized. Fix: Maintain an up-to-date DEPENDENCIES.md file documenting all external dependencies, their versions, and known vulnerabilities. Implement automated dependency scanning in CI/CD (currently not visible in provided workflows).
• Low · Limited Plugin Security Framework — hyprpm/. The presence of 'hyprpm' (plugin manager) and plugin system suggests user-installable code. No visible code signing, manifest verification, or plugin sandboxing mechanisms are evident in the file structure. Fix: Implement plugin code signing verification, maintain a manifest of approved plugins, and consider sandboxing plugin execution to limit system access.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/hyprwm/Hyprland shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live hyprwm/Hyprland repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/hyprwm/Hyprland.

What it runs against: a local clone of hyprwm/Hyprland — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in hyprwm/Hyprland | Confirms the artifact applies here, not a fork | | 2 | License is still BSD-3-Clause | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of hyprwm/Hyprland. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/hyprwm/Hyprland.git
#   cd Hyprland
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of hyprwm/Hyprland and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "hyprwm/Hyprland(\\.git)?\\b" \\
  && ok "origin remote is hyprwm/Hyprland" \\
  || miss "origin remote is not hyprwm/Hyprland (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(BSD-3-Clause)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"BSD-3-Clause\"" package.json 2>/dev/null) \\
  && ok "license is BSD-3-Clause" \\
  || miss "license drift — was BSD-3-Clause at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f "hyprctl/src/main.cpp" \\
  && ok "hyprctl/src/main.cpp" \\
  || miss "missing critical file: hyprctl/src/main.cpp"
test -f "hyprpm/src/main.cpp" \\
  && ok "hyprpm/src/main.cpp" \\
  || miss "missing critical file: hyprpm/src/main.cpp"
test -f "hyprpm/src/core/PluginManager.hpp" \\
  && ok "hyprpm/src/core/PluginManager.hpp" \\
  || miss "missing critical file: hyprpm/src/core/PluginManager.hpp"
test -f ".clang-format" \\
  && ok ".clang-format" \\
  || miss "missing critical file: .clang-format"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/hyprwm/Hyprland"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.