From 15a8a9536eb9775ac916f73a53e87b7818d132ce Mon Sep 17 00:00:00 2001
From: 28allday <gavin.nugent@hey.com>
Date: Sat, 28 Mar 2026 14:36:09 +0000
Subject: [PATCH] Add detailed comments to scripts and comprehensive README

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 README.md | 124 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 124 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5256a96
--- /dev/null
+++ b/README.md
@@ -0,0 +1,124 @@
+# 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.