HyprMon

HyprMon is a TUI (Terminal User Interface) tool for configuring monitors on Arch Linux running Wayland with Hyprland. It provides a visual "desk map" where you can arrange monitors using keyboard and mouse controls, with real-time application to Hyprland.

Features

• Visual Monitor Layout: See all your monitors as proportional boxes in a spatial map
• Keyboard & Mouse Control: Move monitors with arrow keys or drag them with your mouse
• Smart Snapping: Automatic edge and center alignment with visual guides
• Grid Movement: Configurable grid sizes (1, 8, 16, 32, 64 pixels)
• Scale Selection: Interactive menu with common DPI scaling values (0.5x to 3.0x)
• Resolution & Refresh Rate: Choose from all available display modes (1080p@144Hz, 4K@60Hz, etc.)
• Advanced Display Settings: Color depth (8/10-bit), color management (sRGB/Wide/HDR), VRR, rotation/transform
• HDR Support: HDR color mode with SDR brightness and saturation controls
• Monitor Mirroring: Mirror one monitor to another with visual feedback and circular dependency prevention
• Visual Indicators: Monitor boxes show HDR, 10-bit, VRR, transform status, and mirror relationships
• Live Apply: Instantly apply changes to Hyprland or save them to configuration
• Safe Rollback: Revert to previous configuration if something goes wrong
• Automatic Backups: Creates timestamped backups before modifying config files
• Monitor Profiles: Save and restore different monitor configurations

Screenshots

Installation

Arch Linux

yay -S hyprmon-bin

Nix

Try it!

If you have Nix setup you can try out hyprmon without installing it:

nix run nixpkgs#hyprmon

From Nixpkgs

{pkgs, ... }: {
  environment.systemPackages = [ # or home.packages
    pkgs.hyprmon
  ];
}

Prerequisites

• Go 1.20 or higher
• Hyprland window manager
• hyprctl command available
• Optional: wlr-randr for additional monitor detection

Build from Source

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

Usage

Main UI

hyprmon

Profile Management

# Apply a saved profile directly
hyprmon --profile work

# Show profile selection menu
hyprmon profiles

Keyboard Controls (Main UI)

Key	Action
↑↓←→ or hjkl	Move selected monitor by grid size
Shift+↑↓←→	Move by 10× grid size
Tab / Shift+Tab	Cycle through monitors
G	Change grid size (1, 8, 16, 32, 64 px)
L	Toggle snap mode (Off, Edges, Centers, Both)
R	Open scale selector with common DPI values
F	Open resolution & refresh rate mode picker
[ / ]	Decrease/Increase scale by 0.05
Enter or Space	Toggle monitor active/inactive
C or D	Open advanced display settings dialog
M	Open monitor mirroring configuration
A	Apply changes live to Hyprland
S	Save changes to configuration file
P	Save current layout as named profile
Z	Revert to previous configuration
Q or Ctrl+C	Quit

Mouse Controls

Action	Effect
Left Click	Select monitor
Left Drag	Move monitor (with snapping)
Right Click	Toggle monitor active/inactive
Scroll Wheel	Adjust monitor scale

Visual Indicators

• Green boxes: Active monitors
• Gray boxes: Inactive monitors
• Double border: Currently selected monitor
• Alignment guides: Appear when monitors align
• Status badges: HDR, 10-bit, VRR, and rotation indicators on monitor boxes
• Mirror indicators: →source (mirroring from) and ←target (mirroring to) with dotted lines

Advanced Display Settings

Press C or D in the main UI to open the advanced display settings dialog for the selected monitor. This allows you to configure:

Color Settings

• Color Depth: Switch between 8-bit and 10-bit color depth
• Color Mode: Choose from Auto, sRGB, Wide, HDR, or HDR-EDID color management
• SDR Controls: When in HDR mode, adjust SDR brightness (0.5-2.0) and saturation (0.5-1.5)

Display Features

• VRR (Variable Refresh Rate): Configure VRR mode as Off, On, or Fullscreen-only
• Transform: Set monitor rotation (Normal, 90°, 180°, 270°) or flipping

Advanced Dialog Controls

Key	Action
Tab / ↑↓	Navigate between settings
Space	Toggle boolean settings
←→	Adjust slider values (SDR brightness/saturation)
Enter	Apply changes and close dialog
Esc	Cancel changes and close dialog

Monitor Mirroring

Press M in the main UI to configure monitor mirroring for the selected monitor. This allows you to:

• Mirror to another monitor: Show the same content on both displays
• Visual feedback: See mirror relationships with directional indicators and dotted lines
• Circular dependency prevention: Automatically prevents invalid mirror chains (A→B→C→A)
• Real-time validation: Immediate feedback if a mirror configuration would be invalid

Mirror Configuration Controls

Key	Action
↑↓	Navigate between available source monitors
Enter	Set selected monitor as mirror source
D	Disable mirroring (no source)
Esc	Cancel and close mirror picker

Mirror Troubleshooting

• Invalid mirror chains: The system prevents circular dependencies where monitors mirror each other in a loop
• Source not available: Ensure the source monitor is active and not already mirroring another display
• Performance: Mirroring may impact performance depending on resolution and refresh rate differences

Profiles

HyprMon supports saving and loading monitor configurations as profiles, perfect for different setups like home, work, or presentation modes.

Creating Profiles

• In the main UI, press P to save the current layout
• Enter a descriptive name (e.g., "home", "work", "laptop")
• Confirm overwrite if a profile with that name exists
• Profiles are stored in ~/.config/hyprmon/profiles/

Using Profiles

# Quick switch via command line (perfect for keybindings)
hyprmon --profile home
hyprmon --profile work
hyprmon --profile laptop-only

# Interactive profile menu - shows all saved profiles
hyprmon profiles

The profile menu allows you to:

• Select and apply any saved profile
• Delete profiles with 'D' key
• Open the full UI for creating new profiles

Hyprland Keybindings

Add these to your hyprland.conf for quick profile switching:

bind = $mainMod, F1, exec, hyprmon --profile home
bind = $mainMod, F2, exec, hyprmon --profile work
bind = $mainMod, F3, exec, hyprmon --profile laptop
bind = $mainMod, F4, exec, hyprmon profiles

Laptop Lid / Clamshell Mode

HyprMon profiles can be used for laptop clamshell mode by combining them with Hyprland's lid switch bindings. Create two profiles — one for docked use (laptop display off, external monitor only) and one for laptop-only use — then add these lines to your hyprland.conf:

bindl = , switch:on:Lid Switch, exec, hyprmon --profile docked
bindl = , switch:off:Lid Switch, exec, hyprmon --profile laptop

When the lid closes, HyprMon will apply the "docked" profile, disable the laptop display, save the configuration, and automatically migrate workspaces to the external monitor. When the lid opens, the "laptop" profile restores the internal display.

Note: You may need to set HandleLidSwitch=ignore in /etc/systemd/logind.conf to prevent systemd from suspending the laptop when the lid closes.

Stable monitor matching with desc: format

By default, HyprMon writes monitor lines keyed by connector name (e.g., monitor=DP-9,…). For daisy-chained or otherwise indistinguishable monitors, the kernel may assign connector names in a different order across reboots or replugs, which swaps monitor positions.

Hyprland supports matching by EDID description instead:

monitor=desc:Dell Inc. DELL U3419W 5HJB6T2,3440x1440@60,0x0,1.00

To opt in per monitor:

1. Select the monitor and press c (or d) to open advanced settings.
2. Toggle Write as desc: to On.
3. Save your configuration (S) to write hyprland.conf in the new format.

The toggle is unavailable when the monitor has no EDID description, when two or more connected monitors share the same description (typically identical monitors without a serial number), or when the description contains characters Hyprland cannot parse. The preference persists across sessions in ~/.config/hyprmon/settings.json and is also stored inside any profile you save that includes the monitor.

Live application via hyprctl continues to use connector names — the desc: format applies only to the persisted hyprland.conf.

Configuration

HyprMon reads and writes to your Hyprland configuration file. The location is determined in this order:

1. $HYPRLAND_CONFIG environment variable
2. ~/.config/hypr/hyprland.conf (default)

Backup Files

Before any configuration changes, HyprMon creates a backup:

• Location: hyprland.conf.bak.<timestamp>
• These backups are never automatically deleted

How It Works

1. Reading: HyprMon uses hyprctl monitors -j to read current monitor configuration
2. Applying: Live changes use hyprctl keyword monitor ... commands
3. Saving: Updates only the monitor= lines in your hyprland.conf
4. Rollback: Maintains previous state for quick reversion

Terminal Requirements

• Requires a terminal with SGR mouse support
• If using tmux, enable mouse mode: set -g mouse on
• Recommended terminal size: 80×24 or larger

Safety Features

• Automatic Backups: Creates timestamped backups before any config changes
• Safe Apply: Preview changes before applying
• Rollback Support: Quick revert to last working configuration
• Non-destructive: Only modifies monitor lines in config

Troubleshooting

Monitors Not Detected

• Ensure hyprctl is available and Hyprland is running
• Try installing wlr-randr for additional monitor detection

Mouse Not Working

• Enable mouse support in your terminal
• For tmux users: Add set -g mouse on to your tmux.conf

Changes Not Persisting

• Check write permissions for your hyprland.conf
• Verify the config path with echo $HYPRLAND_CONFIG

Future Features (Roadmap)

• Monitor profiles (Home, Work, Presentation modes)
• Advanced display settings (color depth, HDR, VRR, rotation)
• DPI-aware positioning (accounts for monitor scale in layout)
• Resolution and refresh rate picker
• Monitor mirroring with circular dependency prevention
• Alignment menu (distribute, same size, etc.)
• Auto-switching profiles on monitor hotplug

License

Apache License 2.0 - See LICENSE file for details

Copyright 2025 Eran Sandler

Development

Setting up development environment

git clone https://github.com/eransandler/hyprmon.git
cd hyprmon
make deps        # Install dependencies
make hooks       # Install git pre-commit hooks
make build       # Build the application

CI/CD Workflows

• CI: Runs on every push to main - tests, linting, build verification
• Release: Only runs on version tags (v*) - builds binaries and creates GitHub release
• PR Checks: Runs on pull requests - comprehensive testing and security scanning

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.

Acknowledgments

Built with:

• Bubble Tea - Terminal UI framework
• Lip Gloss - Style definitions
• Hyprland - Wayland compositor