HyprMon puts a drag-and-drop desk map in front of your Hyprland monitors

A desk map drawn in the terminal, not a settings dialog

HyprMon is a TUI monitor configuration tool for Hyprland on Arch Linux running Wayland. The README describes it as providing a visual desk map where you arrange monitors with keyboard and mouse controls, with real-time application to Hyprland.

The desk map is the idea. Every monitor is drawn as a proportional box in a spatial layout, so the arrangement on screen mirrors the arrangement on your desk. You move a box with the arrow keys or hjkl, or you drag it with the mouse, and the box snaps to other monitors' edges and centers with alignment guides appearing when things line up.

Two key families sit side by side. The keyboard path is the one the tool is built around, with a full table of bindings in the README. Grid movement uses arrow keys or hjkl and moves by the current grid size, Shift plus arrows moves by ten times that, and Tab cycles through monitors. The mouse path is thinner but real: left click selects, left drag moves with snapping, right click toggles a monitor active or inactive, and the scroll wheel adjusts scale.

Because the tool is a terminal application, it inherits the terminal's own limits, and the README does not describe any way around them.

Applying live to Hyprland or saving to the config file

The distinction between applying and saving is central to the design, and it is the reason the tool can be used safely.

The `A` key applies changes live to Hyprland, so the reconfiguration happens immediately on the running session. The `S` key saves the same changes to the configuration file, making them permanent. That gives you a way to try a layout without committing to it, which matters when you are moving a 4K panel around and want to see the result before the file changes.

On top of that there are two safety nets. `Z` reverts to the previous configuration, and the feature list calls this safe rollback. The tool also creates timestamped backups before modifying config files, which is a separate mechanism from the in-app revert.

The config files it touches are Hyprland's, and the profiles it manages live under `~/.config/hyprmon/profiles/`. The README describes live application as instantaneous, and `Ctrl+R` reloads monitors from Hyprland, which is how you pull in a change made outside the tool.

Picking scale, resolution and refresh rate from menus

The per-monitor settings are where the tool does its practical work.

`R` opens a scale selector with common DPI values, the README placing the range from 0.5x to 3.0x, and the bracket keys decrease or increase scale by 0.05 for fine adjustment. `F` opens a resolution and refresh rate mode picker that lists all available display modes, with 1080p at 144Hz and 4K at 60Hz given as examples of what you might see in the list.

`G` changes the grid size, with the choices given as 1, 8, 16, 32 and 64 pixels. Grid size is the movement increment for the arrow keys, so a coarse grid is for roughly positioning a monitor and a fine grid is for pixel-perfect alignment.

`L` toggles snap mode, with the options Off, Edges, Centers and Both. Snapping is what keeps a monitor from ending up at a fractional position that looks nearly but not quite aligned, and the mode selector lets you keep center snapping while disabling edge snapping if a particular arrangement calls for it.

`C` or `D` opens the advanced display settings dialog, and `M` opens the mirroring picker, both of which are separate screens with their own key tables in the README.

The advanced dialog covers color depth, HDR, VRR and rotation

The advanced dialog is where the tool reaches beyond geometry into the parts of display configuration that are tedious to write by hand.

Color depth can be set to 8-bit or 10-bit. Color mode offers Auto, sRGB, Wide, HDR and HDR-EDID. When you are in HDR mode, the SDR controls become relevant, with brightness on a 0.5 to 2.0 range and saturation on a 0.5 to 1.5 range, which is how you keep the rest of the desktop readable when one panel is showing HDR content.

VRR is configurable as Off, On or Fullscreen-only, and Transform sets rotation to Normal, 90, 180 or 270 degrees, or flipping. Inside the dialog, Tab and the arrow keys navigate, Space toggles boolean settings, left and right adjust the slider values, Enter applies and closes, and Esc cancels and closes.

The main screen gives you a visual summary of all this. The README says monitor boxes show status badges for HDR, 10-bit, VRR and transform, and that green boxes are active monitors while gray boxes are inactive, with a double border marking the selected one. So you can read the state of every display at a glance rather than opening four dialogs to check.

Mirroring with circular dependency prevention

Monitor mirroring is a first-class feature rather than something you configure by hand in the Hyprland config, and it comes with one specific safeguard.

Press `M` on the selected monitor and you get a picker listing available source monitors. Enter sets the selected monitor as a mirror source, `D` disables mirroring, and Esc closes the picker. The feature list also calls out visual feedback, with directional indicators and dotted lines drawn between a source and its target, using arrows to show which way the mirroring runs.

The safeguard is circular dependency prevention. The README is explicit that the system prevents invalid mirror chains such as A pointing at B pointing at C pointing back at A, and that you get immediate feedback if a mirror configuration would be invalid. Its troubleshooting section adds the related condition: the source monitor has to be active and must not already be mirroring another display.

The README also flags a performance caveat. Mirroring may cost performance depending on the resolution and refresh rate differences between the two panels, which is worth knowing before you mirror a 60Hz screen to a 144Hz one.

The visual indicators tie the mirroring feature into the rest of the UI, with the boxes showing mirror relationships alongside the other badges.

Profiles are directories, and the CLI can list them as JSON

Monitor profiles exist because the same machine has more than one reasonable arrangement. The README gives home, work and presentation modes as the model, and stores profiles as files in `~/.config/hyprmon/profiles/`.

Creating one is done from inside the UI. Press `P` to save the current layout, enter a descriptive name such as home, work or laptop, and confirm the overwrite if a profile with that name already exists.

The command line is the more interesting part, because it is designed to be driven from a keybinding. A profile can be applied directly by name:

hyprmon --profile home
hyprmon --profile work
hyprmon --profile laptop-only

The interactive menu lists all saved profiles, and two listing options exist for scripting. `--list-profiles` prints the available names with the active one marked with an asterisk, and `--list-profiles --json` formats them as an array of objects with name and is_active keys. The README names Waybar and Eww as the intended consumers of that JSON, which tells you the output is meant to be piped into a status bar rather than read by a person.

That makes HyprMon useful as a backend for a panel indicator as well as a standalone tool.

Building from source, and the Go version mismatch in the docs

The README documents three ways to get the binary, and the source build is the one to read carefully.

On Arch Linux there is an AUR package, installed with `yay -S hyprmon-bin`. On Nix you can try the tool without installing it at all:

nix run nixpkgs#hyprmon

There is also a Nixpkgs module, which adds the package to `environment.systemPackages` or `home.packages`.

Building from source is a clone and a Go build:

git clone https://github.com/erans/hyprmon.git
cd hyprmon
go build -o hyprmon
sudo mv hyprmon /usr/local/bin/

The prerequisites listed in the README are Go 1.20 or higher, the Hyprland window manager, and the `hyprctl` command available, with `wlr-randr` optional for additional monitor detection. There is a contradiction worth noticing: go.mod declares go 1.26, while the README says Go 1.20 or higher. A Go 1.20 toolchain will not build a module that declares 1.26, so the README's requirement is out of date.

The Makefile is where the packaging details live. It builds into ./bin, and the version string is injected at link time from `git describe --tags --always --dirty`, the short commit hash, the build date and the Go version, with -s -w for stripped symbols. Targets exist for build, run, install, uninstall, clean and test, and the build target runs fmt-check and lint first.

Apache-2.0, an update path, and a repository shaped around the TUI

The licence is Apache-2.0, with the LICENSE file at the repository root. That is a permissive licence with an explicit patent grant, and it carries no practical obstacle to using the tool or building on its code. This is not legal advice, and the file itself is the authority for any use you have in mind.

The repository is not archived, and the last push was on 2026-10-13, with release v0.0.17 published on 2026-05-18 and v0.0.16 earlier the same day. The version numbers are still in the 0.0.x range, which tells you the author treats this as a tool whose interface may still change.

The file layout mirrors the feature list closely enough to be a map of the code. There are separate files for the mirroring picker, the scale picker, the mode picker and the advanced settings, plus hyprland.go for talking to the compositor, hardware_id.go for identifying the display hardware, profiles.go for the profile store, update.go for self-update, and view.go for the rendering. Tests exist alongside the main pieces, including hardware_id_test.go, hyprland_test.go, mirror_test.go, models_test.go and settings_test.go, and the Makefile's test target runs `go test -v ./...`.

The dependency list is small and tells you the tool's centre of gravity. It is built on the Charm libraries, with bubbletea for the event loop, bubbles for the widgets and lipgloss for styling, plus golang.org/x/term for terminal handling. Everything the tool knows about Hyprland it knows through the command line, not through a library.

Editorial conclusion

HyprMon is worth adopting for a Hyprland user on Arch Linux who changes monitor layouts often, who wants one profile per setup, and who would rather not hand-edit the monitor blocks in a Hyprland config. It is the wrong tool for anyone not running Hyprland, for a Wayland session without the hyprctl command, and for a setup where a display is driven by hardware rather than by the compositor. Before building it, check the Go requirement, since the README says Go 1.20 or higher while go.mod declares go 1.26, and confirm that hyprctl is on your PATH, because every live apply and reload goes through it.

Frequently asked questions

Official sources

1. erans/hyprmon on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases