lenovo-gentoo/scripts/monitor-setup

Monitor Setup Tool

Easy monitor management for Gentoo + Hyprland using hyprctl.

Features

• 📺 Show current monitor layout and configuration
• 🔄 Swap left/right external monitor positions
• 📋 List all detected monitors with details
• 🔁 Reset to automatic configuration
• ✨ Color-coded output with visual layout representation
• ⚡ ZSH autocompletion support

Installation

# From the scripts folder
cd scripts/monitor-setup

# Install the main script
sudo cp monitor-setup /usr/local/bin/monitor-setup
sudo chmod +x /usr/local/bin/monitor-setup

# Install ZSH autocompletion
sudo mkdir -p /usr/local/share/zsh/site-functions
sudo cp _monitor-setup /usr/local/share/zsh/site-functions/_monitor-setup

# Reload ZSH completions (or restart your shell)
autoload -U compinit && compinit

Requirements

• hyprctl (comes with Hyprland)
• jq for JSON parsing
• Hyprland window manager running

# Install jq if not already installed
sudo emerge -av app-misc/jq

Usage

Show current monitor status

monitor-setup
# or
monitor-setup status

This displays:

• All active monitors
• Resolution, refresh rate, and position for each
• Visual ASCII layout representation

List all monitors

monitor-setup list

Shows detailed information about each detected monitor including:

• Monitor ID and name
• Description and model
• Resolution and refresh rate
• Position and scale
• Active workspace

Swap external monitors (Fix left/right order)

monitor-setup swap

Swaps the position of two external monitors. This is useful when:

• Physical monitor arrangement doesn't match logical arrangement
• After docking/undocking your laptop
• After system updates that reset monitor positions

Requirements: Exactly 2 external monitors must be connected

Reset to automatic configuration

monitor-setup reset

Resets monitor configuration to automatic detection. This will:

• Run the automatic monitor-setup script if available (~/.config/hypr/scripts/monitor-setup.sh)
• Otherwise, reset all monitors to auto-detection mode

Useful after:

• Reconnecting a dock
• Monitor connection issues
• Display glitches

Get help

monitor-setup help

Common Use Cases

Fix reversed external monitors

# Check current layout
monitor-setup

# If left/right are reversed, swap them
monitor-setup swap

# Verify the change
monitor-setup status

After docking laptop

# Reset to automatic detection
monitor-setup reset

# Check the layout
monitor-setup status

# If monitors are in wrong order
monitor-setup swap

Check monitor details before configuration

# List all monitors with full details
monitor-setup list

ZSH Autocompletion

Once installed, ZSH will provide intelligent completions:

• Command completion: monitor-setup <TAB>
• Shows available commands with descriptions

Integration with Hyprland

This tool is designed to work alongside the automatic monitor setup script at ~/.config/hypr/scripts/monitor-setup.sh.

Differences:

• Automatic script: Runs on dock/undock events, handles lid state
• This tool: Manual interactive management for quick adjustments

Troubleshooting

"Hyprland is not running"

Make sure Hyprland is your active window manager:

pgrep -x Hyprland

"hyprctl command not found"

Ensure hyprctl is in your PATH. It should be installed with Hyprland.

"jq command not found"

Install jq for JSON parsing:

sudo emerge -av app-misc/jq

Swap command says "requires exactly 2 external monitors"

The swap command only works when you have exactly 2 external monitors connected. Check with:

monitor-setup list

Changes don't persist after reboot

This tool makes runtime changes to Hyprland. To make permanent changes, update your Hyprland configuration file (~/.config/hypr/hyprland.conf) or use the automatic setup script.

Examples

Quick monitor check

# Show current configuration
monitor-setup

# Output will show:
# - Number of active monitors
# - Each monitor's resolution, position, scale
# - Visual layout representation

Fix monitor order issue

# Problem: Left monitor appears on right, right monitor on left
monitor-setup swap

# Monitors are now in correct order

After dock reconnection

# Monitors not detected properly
monitor-setup reset

# If order is wrong after reset
monitor-setup swap

Visual Layout

The tool shows a visual representation of your monitor layout:

Monitor Configuration:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Active Monitors: 2

  DVI-I-1:
    Resolution: 2560x1440@60Hz
    Position: 0x0
    Scale: 1.00
    Type: External Display

  DVI-I-2:
    Resolution: 2560x1440@60Hz
    Position: 2560x0
    Scale: 1.00
    Type: External Display

Layout:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ┌────────────┐  ┌────────────┐
  │ DVI-I-1    │  │ DVI-I-2    │
  └────────────┘  └────────────┘

Related

• Audio Setup: See scripts/audio-setup/ for audio device management
• WiFi Setup: See scripts/wifi-setup/ for WiFi management
• Bluetooth Setup: See scripts/bluetooth-setup/ for Bluetooth management

Future Enhancements

Planned features for future versions (contributions welcome!):

• Save/load monitor layout presets
• Support for monitor rotation
• Per-monitor refresh rate adjustment
• Workspace-to-monitor assignments
• Integration with waybar for quick access