# Monitor TUI - Omarchy

A terminal user interface for managing monitor settings in [Omarchy](https://omarchy.com) (Hyprland). Change resolution, scaling, position, and refresh rate without editing config files.

## Quick Start

```bash
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

```bash
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](https://omarchy.com) - The Arch Linux distribution this was built for
- [Hyprland](https://hyprland.org/) - Wayland compositor

## License

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