Monitor-TUI-Omarchy/README.md

Monitor TUI - Omarchy

A terminal user interface for managing monitor settings in Omarchy (Hyprland). Change resolution, scaling, position, and refresh rate without editing config files.

Quick Start

git clone https://github.com/28allday/Monitor-TUI-Omarchy.git
cd Monitor-TUI-Omarchy
chmod +x monitor-tui.sh
./monitor-tui.sh

On first run, the script installs itself to ~/.local/bin/monitor-tui and adds a keybind (SUPER+ALT+M) so you can open it anytime.

Features

Feature	Description
Resolution	Choose from all available modes reported by your monitor
Refresh rate	Select from supported rates (60Hz, 144Hz, 240Hz, etc.)
Scaling	Preset options (1x, 1.25x, 1.5x, 2x) or custom values
Position	Auto, left, right, above, below, or custom coordinates
VRR	Enable/disable Variable Refresh Rate (FreeSync/G-Sync)
Multi-monitor	Configure each display independently, auto-calculate positions
Live preview	Changes apply instantly — no restart needed
Backup/restore	Automatic backup before changes, easy restore

How It Works

1. Reads live monitor data from hyprctl monitors -j
2. Shows a menu with your current settings and available options
3. Applies changes instantly via hyprctl keyword (live, no restart)
4. Saves to ~/.config/hypr/monitors.conf for persistence across reboots

Keybind

After installation, press SUPER+ALT+M to open the monitor TUI from anywhere.

The keybind is added to ~/.config/hypr/bindings.conf inside a marked block so it can be cleanly removed by the uninstaller.

Dependencies

Dependency	Purpose	Included in Omarchy?
hyprctl	Reads monitor info and applies changes	Yes (comes with Hyprland)
jq	Parses JSON output from hyprctl	Yes
bc	Floating-point math for scale calculations	Usually yes

Multi-Monitor Setup

When you have multiple monitors, the TUI:

1. Shows all connected displays with their current settings
2. Lets you configure each one independently
3. Auto-calculates position when you choose "Right of", "Above", or "Below"
4. Accounts for scaling when calculating positions (uses logical pixels)

Position Calculation

The TUI calculates positions using logical (scaled) dimensions, not raw pixels. For example:

• A 4K monitor at 2x scale = 1920 logical pixels wide
• A 1080p monitor at 1x scale = 1920 logical pixels wide
• Placing the 1080p monitor to the right: position = 1920x0

Files

Path	Purpose
~/.local/bin/monitor-tui	Installed script
~/.config/hypr/monitors.conf	Monitor configuration (edited by TUI)
~/.config/hypr/monitors.conf.bak	Automatic backup before changes
~/.config/hypr/bindings.conf	Keybind added here (SUPER+ALT+M)
~/.config/hypr/.monitor-tui-installed	Marker file tracking installation

Uninstalling

chmod +x monitor-tui-uninstall.sh
./monitor-tui-uninstall.sh

This removes:

• The installed script from ~/.local/bin/
• The keybind from ~/.config/hypr/bindings.conf
• The window rules from Hyprland config
• The installation marker

Your monitor configuration (monitors.conf) is not removed.

Troubleshooting

TUI shows "No monitors detected"

• Make sure you're running inside Hyprland: echo $XDG_CURRENT_DESKTOP
• Check hyprctl works: hyprctl monitors

Changes don't persist after reboot

• Check the config file was written: cat ~/.config/hypr/monitors.conf
• Make sure monitors.conf is sourced in your main config:

  # In ~/.config/hypr/hyprland.conf
  source = ~/.config/hypr/monitors.conf
  

Scale looks wrong

• Hyprland works best with specific scale values: 1, 1.25, 1.333333, 1.5, 1.666667, 1.75, 2
• Fractional scaling can cause blurry text in some XWayland apps

SUPER+ALT+M doesn't work

• Check the keybind was added: grep "monitor-tui" ~/.config/hypr/bindings.conf
• Reload Hyprland: hyprctl reload

Credits

• Omarchy - The Arch Linux distribution this was built for
• Hyprland - Wayland compositor

License

This project is provided as-is for the Omarchy community.