Tutorial: Automatic monitor switching

[mwaltzer]

Automatic Monitor Switching Tutorial

Hyprland users often jump between laptop-only, docked, and dual-display setups. This tutorial packages everything needed to mirror my automatic lid-handling system without requiring access to my private ~/.dotfiles, just copy the snippets below into your own folder.

What this gives you

• Lid close → external-only layout when a DP/HDMI monitor is connected (otherwise laptop-only).
• Lid open → dual display with configurable workspace groupings.
• Hyprland startup/reload → layouts reassert automatically (handles “boot with lid closed”).
• DP/HDMI auto-detection, logging via journalctl -t lid-events, and handy manual aliases.

The instructions assume:

• Hyprland 0.51+ running on Arch Linux (or an equivalent Wayland environment where you can translate package/service commands).
• sudo access.
• Basic familiarity with copying files into place.

---

Step 0 – Prepare a working directory

Create a workspace that mirrors the layout expected by the installer (acpi/ and scripts/ as siblings). Feel free to pick a different location; just stay consistent.

mkdir -p ~/monitor-auto-switch/{acpi,scripts}
cd ~/monitor-auto-switch

---

Step 1 – Create the ACPI helper scripts

Copy each snippet into the indicated file. Adjust the configuration block in hypr-utils.sh so it matches your hardware (connector names, resolutions, scales, workspace layout).

1.1 acpi/hypr-utils.sh

cat <<'EOF' > ~/monitor-auto-switch/acpi/hypr-utils.sh
#!/bin/bash
set -euo pipefail

umask 022
PATH=/usr/local/bin:/usr/bin:/bin

log() {
  logger -t lid-events "[$0] $*"
}

# ========== CONFIGURATION SECTION ==========
# Customize these values based on your hardware
LAPTOP_MONITOR="eDP-1"                    # Your laptop display name
EXTERNAL_MONITOR="DP-1"                   # Your external display name
EXTERNAL_RESOLUTION="3840x2560@60"        # External monitor resolution@refresh
LAPTOP_RESOLUTION="1920x1200@60"          # Laptop monitor resolution@refresh
EXTERNAL_SCALE="1.67"                     # External monitor scaling factor
LAPTOP_SCALE="1"                           # Laptop monitor scaling factor
EXTERNAL_POSITION="0x0"                   # External monitor position
LAPTOP_POSITION_DUAL="2300x0"            # Laptop position in dual mode
LAPTOP_POSITION_SOLO="0x0"               # Laptop position when alone
# Workspace distribution
EXTERNAL_WS="${EXTERNAL_WS:-1 2 3 4 5}"  # Workspaces for external monitor
LAPTOP_WS="${LAPTOP_WS:-6 7 8 9 10}"     # Workspaces for laptop monitor
# ========== END CONFIGURATION SECTION ==========

# Debounce: single instance at a time
exec 9>/run/lid-switch.lock || true
if command -v flock >/dev/null 2>&1; then
  flock -n 9 || { log "Another lid handler instance running, exiting."; exit 0; }
fi

require_cmd() { command -v "$1" >/dev/null 2>&1 || { log "Missing command: $1"; exit 1; }; }
require_cmd hyprctl
require_cmd logger

get_hypr_user() {
  local u
  u=$(ps -o user= -C Hyprland | head -n1 || true)
  if [ -z "$u" ]; then
    u=$(ps aux | grep -E '[Hh]yprland' | awk '{print $1}' | head -n1 || true)
  fi
  echo "$u"
}

export_hypr_env() {
  HYPR_USER="${HYPR_USER:-$(get_hypr_user)}"
  if [ -z "$HYPR_USER" ]; then
    log "Hyprland user not found."
    return 1
  fi
  local pid
  pid=$(pgrep -u "$HYPR_USER" -x Hyprland | head -n1 || true)
  if [ -z "$pid" ]; then
    pid=$(pgrep -u "$HYPR_USER" -f '[Hh]yprland' | head -n1 || true)
  fi
  if [ -z "$pid" ]; then
    log "Hyprland PID not found for user $HYPR_USER."
    return 1
  fi
  
  # Get XDG_RUNTIME_DIR from the process environment
  XDG_RUNTIME_DIR=$(cat /proc/"$pid"/environ | tr '\0' '\n' | awk -F= '$1=="XDG_RUNTIME_DIR"{print $2}')
  if [ -z "$XDG_RUNTIME_DIR" ]; then
    XDG_RUNTIME_DIR="/run/user/$(id -u "$HYPR_USER")"
  fi
  
  # Try to get HYPRLAND_INSTANCE_SIGNATURE from the process environment
  HYPR_SIG=$(cat /proc/"$pid"/environ | tr '\0' '\n' | awk -F= '$1=="HYPRLAND_INSTANCE_SIGNATURE"{print $2}')
  
  # If not found (e.g., UWSM managed), try to find the most recent socket directory
  if [ -z "$HYPR_SIG" ]; then
    # Look for the most recent Hyprland socket directory
    local latest_socket=""
    local latest_time=0
    for socket_dir in "$XDG_RUNTIME_DIR"/hypr/*/; do
      if [ -d "$socket_dir" ] && [ -S "${socket_dir}/.socket.sock" ]; then
        local mtime=$(stat -c %Y "$socket_dir" 2>/dev/null || echo 0)
        if [ "$mtime" -gt "$latest_time" ]; then
          latest_time="$mtime"
          latest_socket="$socket_dir"
        fi
      fi
    done
    if [ -n "$latest_socket" ]; then
      HYPR_SIG=$(basename "$latest_socket")
    fi
  fi
  
  if [ -z "$XDG_RUNTIME_DIR" ]; then
    log "Could not determine XDG_RUNTIME_DIR for user $HYPR_USER."
    return 1
  fi
  
  # We can proceed even without HYPR_SIG as hyprctl might work without it
  export HYPR_USER HYPR_SIG XDG_RUNTIME_DIR
  log "Hyprland env: user=$HYPR_USER, XDG_RUNTIME_DIR=$XDG_RUNTIME_DIR, sig=${HYPR_SIG:-'(auto-detect)'}"
}

run_as_hypr() {
  if [ -n "$HYPR_SIG" ]; then
    if command -v runuser >/dev/null 2>&1; then
      runuser -u "$HYPR_USER" -- env HYPRLAND_INSTANCE_SIGNATURE="$HYPR_SIG" XDG_RUNTIME_DIR="$XDG_RUNTIME_DIR" "$@"
    else
      sudo -u "$HYPR_USER" env HYPRLAND_INSTANCE_SIGNATURE="$HYPR_SIG" XDG_RUNTIME_DIR="$XDG_RUNTIME_DIR" "$@"
    fi
  else
    # Try without HYPR_SIG, let hyprctl auto-detect
    if command -v runuser >/dev/null 2>&1; then
      runuser -u "$HYPR_USER" -- env XDG_RUNTIME_DIR="$XDG_RUNTIME_DIR" "$@"
    else
      sudo -u "$HYPR_USER" env XDG_RUNTIME_DIR="$XDG_RUNTIME_DIR" "$@"
    fi
  fi
}

hypr() {
  run_as_hypr hyprctl "$@"
}

monitor_connected_sysfs() {
  local connector="$1" path
  for path in /sys/class/drm/card*-"$connector"/status; do
    [ -r "$path" ] && grep -q '^connected' "$path" && return 0
  done
  return 1
}

monitor_connected_hypr() {
  local connector="$1"
  hypr monitors 2>/dev/null | awk -v name="$connector" '$1=="Monitor" && $2==name {found=1} END {exit !found}'
}

monitor_connected() {
  local connector="$1"
  monitor_connected_sysfs "$connector" || monitor_connected_hypr "$connector"
}

detect_external_monitor() {
  # Keep configured monitor if already connected
  if [ -n "${EXTERNAL_MONITOR:-}" ] && monitor_connected "$EXTERNAL_MONITOR"; then
    log "Using configured external monitor: ${EXTERNAL_MONITOR}"
    return 0
  fi

  local path connector
  for path in /sys/class/drm/card*-DP-*/status; do
    [ -r "$path" ] || continue
    if grep -q '^connected' "$path"; then
      connector=$(basename "$(dirname "$path")")
      connector="${connector#*-}"
      EXTERNAL_MONITOR="$connector"
      export EXTERNAL_MONITOR
      log "Auto-detected external monitor via sysfs: ${EXTERNAL_MONITOR}"
      return 0
    fi
  done

  for path in /sys/class/drm/card*-HDMI-*/status; do
    [ -r "$path" ] || continue
    if grep -q '^connected' "$path"; then
      connector=$(basename "$(dirname "$path")")
      connector="${connector#*-}"
      EXTERNAL_MONITOR="$connector"
      export EXTERNAL_MONITOR
      log "Auto-detected external monitor via HDMI sysfs: ${EXTERNAL_MONITOR}"
      return 0
    fi
  done

  local hypr_candidate
  hypr_candidate=$(hypr monitors 2>/dev/null | awk -v skip="$LAPTOP_MONITOR" '$1=="Monitor" && $2!=skip {print $2; exit}')
  if [ -n "$hypr_candidate" ]; then
    EXTERNAL_MONITOR="$hypr_candidate"
    export EXTERNAL_MONITOR
    log "Auto-detected external monitor via hyprctl: ${EXTERNAL_MONITOR}"
    return 0
  fi

  log "Auto-detect failed: no connected external monitor found."
  return 1
}

external_connected() {
  [ -n "${EXTERNAL_MONITOR:-}" ] || detect_external_monitor
  monitor_connected "${EXTERNAL_MONITOR:-}"
}

# Retry wrapper: wait for external to enumerate (docks/cables can be slow)
external_connected_retry() {
  local attempts="${1:-30}"
  local delay="${2:-0.15}"
  local i=0
  detect_external_monitor || true
  while [ "$i" -lt "$attempts" ]; do
    if external_connected; then
      return 0
    fi
    detect_external_monitor || true
    sleep "$delay"
    i=$((i+1))
  done
  return 1
}

move_ws_to_monitor() {
  local dest="$1"
  shift
  local ws
  for ws in "$@"; do
    hypr dispatch moveworkspacetomonitor "$ws" "$dest" >/dev/null 2>&1 || true
    sleep 0.05
  done
}

set_external_only() {
  # Enable external and disable laptop using configured values
  hypr keyword monitor "${EXTERNAL_MONITOR},${EXTERNAL_RESOLUTION},${EXTERNAL_POSITION},${EXTERNAL_SCALE}"
  sleep 0.25
  hypr keyword monitor "${LAPTOP_MONITOR},disable"
  sleep 0.25
}

set_dual_layout() {
  # External and laptop both enabled, positions/scales from config
  hypr keyword monitor "${EXTERNAL_MONITOR},${EXTERNAL_RESOLUTION},${EXTERNAL_POSITION},${EXTERNAL_SCALE}"
  sleep 0.25
  hypr keyword monitor "${LAPTOP_MONITOR},${LAPTOP_RESOLUTION},${LAPTOP_POSITION_DUAL},${LAPTOP_SCALE}"
  sleep 0.25
}

set_laptop_only() {
  hypr keyword monitor "${EXTERNAL_MONITOR},disable"
  sleep 0.25
  hypr keyword monitor "${LAPTOP_MONITOR},${LAPTOP_RESOLUTION},${LAPTOP_POSITION_SOLO},${LAPTOP_SCALE}"
  sleep 0.25
}

reassert_primary_external() {
  sleep 0.60
  hypr dispatch focusmonitor "${EXTERNAL_MONITOR}"
  hypr dispatch workspace 1
  sleep 0.10
}

notify() {
  if command -v notify-send >/dev/null 2>&1; then
    run_as_hypr notify-send "$@"
  fi
}
EOF

1.2 acpi/lid-close.sh

cat <<'EOF' > ~/monitor-auto-switch/acpi/lid-close.sh
#!/bin/bash
set -euo pipefail
sleep 0.3
. /etc/acpi/hypr-utils.sh || exit 0
log "Lid close event received."

if ! export_hypr_env; then
  log "Hyprland not found, exiting."
  exit 0
fi

# Let Hyprland settle after env export
sleep 0.5
detect_external_monitor || true

if external_connected_retry 40 0.10; then
  log "External ${EXTERNAL_MONITOR} connected. Applying external-only layout."
  set_external_only
  sleep 0.35
  move_ws_to_monitor "$EXTERNAL_MONITOR" 1 2 3 4 5 6 7 8 9 10
  notify "Display" "Lid closed: using external monitor only"
  # Ensure external monitor is awake
  sleep 0.25
  hypr dispatch dpms on
  sleep 0.10
  log "External-only layout applied and workspaces moved."
else
  log "No external monitor detected. Keeping laptop-only layout."
  set_laptop_only
fi
EOF

1.3 acpi/lid-open.sh

cat <<'EOF' > ~/monitor-auto-switch/acpi/lid-open.sh
#!/bin/bash
set -euo pipefail
sleep 0.3
. /etc/acpi/hypr-utils.sh || exit 0
log "Lid open event received."

if ! export_hypr_env; then
  log "Hyprland not found, exiting."
  exit 0
fi

# Let Hyprland settle after env export
sleep 0.5
detect_external_monitor || true

if external_connected_retry 40 0.10; then
  log "External ${EXTERNAL_MONITOR} connected. Applying dual layout."
  set_dual_layout
  sleep 0.35
  move_ws_to_monitor "$EXTERNAL_MONITOR" $EXTERNAL_WS
  sleep 0.15
  move_ws_to_monitor "$LAPTOP_MONITOR" $LAPTOP_WS
  notify "Display" "Lid opened: dual display layout set"
  # Ensure monitors are awake
  sleep 0.25
  hypr dispatch dpms on
  # Delayed re-assert for slow-waking docks; make sure focus/workspace are correct
  reassert_primary_external
  log "Dual layout applied and workspace split enforced."
else
  log "No external monitor detected. Applying laptop-only."
  set_laptop_only
fi
EOF

1.4 acpi/check-lid-on-startup.sh

cat <<'EOF' > ~/monitor-auto-switch/acpi/check-lid-on-startup.sh
#!/bin/bash
set -euo pipefail
# Wait for compositor to initialize sockets and for DRM to settle
sleep 3
. /etc/acpi/hypr-utils.sh || exit 0
log "Startup lid state check beginning."

need_reassert=0

if ! export_hypr_env; then
  log "Hyprland env not ready, skipping startup layout."
  exit 0
fi

detect_external_monitor || true

LID_STATE="unknown"
for f in /proc/acpi/button/lid/*/state; do
  if [ -r "$f" ]; then
    if grep -q closed "$f"; then LID_STATE="closed"; else LID_STATE="open"; fi
    break
  fi
done

if [ "$LID_STATE" = "closed" ] && external_connected; then
  log "Boot with lid closed and external connected. Applying external-only."
  set_external_only
  move_ws_to_monitor "$EXTERNAL_MONITOR" 1 2 3 4 5 6 7 8 9 10
  notify "Display" "Startup: lid closed, using external monitor only"
  need_reassert=1
elif external_connected; then
  log "Boot with lid open and external connected. Applying dual layout."
  set_dual_layout
  move_ws_to_monitor "$EXTERNAL_MONITOR" $EXTERNAL_WS
  move_ws_to_monitor "$LAPTOP_MONITOR" $LAPTOP_WS
  notify "Display" "Startup: dual layout applied"
  need_reassert=1
else
  log "Boot without external. Applying laptop-only."
  set_laptop_only
  notify "Display" "Startup: laptop-only layout"
fi

# Ensure all monitors are awake after configuration
hypr dispatch dpms on
if [ "$need_reassert" -eq 1 ]; then
  reassert_primary_external
fi
log "Startup lid state check complete."
EOF

When you are finished, make the files executable:

chmod +x acpi/hypr-utils.sh acpi/lid-close.sh acpi/lid-open.sh acpi/check-lid-on-startup.sh

---

Step 2 – Add the installer script

Create the installer at ~/monitor-auto-switch/scripts/install-monitor-auto-switch.sh:

cat <<'EOF' > ~/monitor-auto-switch/scripts/install-monitor-auto-switch.sh
#!/usr/bin/env bash
set -euo pipefail

# Monitor Auto-Switch Installer (generalized)
# - Copies ACPI lid/monitor scripts into a destination (default /etc/acpi)
# - Creates ACPI event files (default /etc/acpi/events)
# - Optionally restarts acpid
# Works on any system with acpid + systemd (service name: acpid)

# Defaults (can be overridden by flags)
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
REPO_ROOT="$(dirname "$SCRIPT_DIR")"
REPO_ACPI_DIR="${REPO_ROOT}/acpi"
DEST_DIR="/etc/acpi"
EVENTS_DIR="/etc/acpi/events"
LOG_FILE="/var/log/lid-events.log"
NO_RESTART=0
DRY_RUN=0

usage() {
  cat <<EOF
Usage: sudo $(basename "$0") [options]

Options:
  -s, --src DIR            Source directory containing ACPI scripts (default: "+auto detect+" -> "+script_dir+/../acpi")
  -d, --dest DIR           Destination directory for scripts (default: /etc/acpi)
      --events-dir DIR     Destination directory for ACPI events (default: /etc/acpi/events)
  -n, --dry-run            Print what would be done, do not write
      --no-restart         Do not restart acpid after installing
  -h, --help               Show this help and exit

Expected files in --src:
  hypr-utils.sh, lid-open.sh, lid-close.sh, check-lid-on-startup.sh

Examples:
  sudo $(basename "$0")
  sudo $(basename "$0") --src /path/to/your/acpi --no-restart
  sudo $(basename "$0") -n   # dry-run
EOF
}

# Parse args early (before sudo checks so --help works without root)
parse_args() {
  while [ $# -gt 0 ]; do
    case "$1" in
      -s|--src)
        REPO_ACPI_DIR="${2:-}"; shift 2 || { echo "Missing value for $1" >&2; exit 2; };
        ;;
      -d|--dest)
        DEST_DIR="${2:-}"; shift 2 || { echo "Missing value for $1" >&2; exit 2; };
        ;;
      --events-dir)
        EVENTS_DIR="${2:-}"; shift 2 || { echo "Missing value for $1" >&2; exit 2; };
        ;;
      -n|--dry-run)
        DRY_RUN=1; shift ;;
      --no-restart)
        NO_RESTART=1; shift ;;
      -h|--help)
        usage; exit 0 ;;
      *)
        echo "Unknown option: $1" >&2
        usage
        exit 2
        ;;
    esac
  done
}

need_sudo() {
  if [ "${EUID:-$(id -u)}" -ne 0 ]; then
    echo "Please run as root: sudo $0 [options]" >&2
    exit 1
  fi
}

say() { printf '%s\n' "$*"; }

run_as_user() {
  local user="$1"; shift
  if command -v runuser >/dev/null 2>&1; then
    runuser -u "$user" -- "$@"
  else
    sudo -u "$user" "$@"
  fi
}

backup_if_changed() {
  local src="$1" dest="$2"
  if [ -f "$dest" ] && ! cmp -s "$src" "$dest"; then
    if [ "$DRY_RUN" = 1 ]; then
      say "Would back up $dest -> ${dest}.backup"
    else
      cp -av "$dest" "${dest}.backup"
    fi
  fi
}

install_file() {
  local src="$1" dest="$2" mode="$3"
  if [ "$DRY_RUN" = 1 ]; then
    say "Would install $src -> $dest (mode $mode)"
  else
    install -m "$mode" -o root -g root "$src" "$dest"
  fi
}

install_from_repo() {
  mkdir -p "$DEST_DIR" "$EVENTS_DIR"

  backup_if_changed "$REPO_ACPI_DIR/hypr-utils.sh" "$DEST_DIR/hypr-utils.sh"
  install_file      "$REPO_ACPI_DIR/hypr-utils.sh" "$DEST_DIR/hypr-utils.sh" 0755

  backup_if_changed "$REPO_ACPI_DIR/lid-open.sh" "$DEST_DIR/lid-open.sh"
  install_file      "$REPO_ACPI_DIR/lid-open.sh"  "$DEST_DIR/lid-open.sh"  0755

  backup_if_changed "$REPO_ACPI_DIR/lid-close.sh" "$DEST_DIR/lid-close.sh"
  install_file      "$REPO_ACPI_DIR/lid-close.sh" "$DEST_DIR/lid-close.sh" 0755

  backup_if_changed "$REPO_ACPI_DIR/check-lid-on-startup.sh" "$DEST_DIR/check-lid-on-startup.sh"
  install_file      "$REPO_ACPI_DIR/check-lid-on-startup.sh" "$DEST_DIR/check-lid-on-startup.sh" 0755
}

update_events() {
  if [ "$DRY_RUN" = 1 ]; then
    say "Would write $EVENTS_DIR/lid-close with regex event"
    say "Would write $EVENTS_DIR/lid-open with regex event"
  else
    install -m 0644 -o root -g root /dev/stdin "$EVENTS_DIR/lid-close" <<'EOF'
event=button/lid.*close
action=/etc/acpi/lid-close.sh
EOF
    install -m 0644 -o root -g root /dev/stdin "$EVENTS_DIR/lid-open" <<'EOF'
event=button/lid.*open
action=/etc/acpi/lid-open.sh
EOF
  fi
}

post_install() {
  # Ensure log file exists and is writable by both root and user sessions
  if [ "$DRY_RUN" = 1 ]; then
    say "Would touch $LOG_FILE and chmod 666"
  else
    touch "$LOG_FILE"
    chmod 666 "$LOG_FILE" || true
  fi

  if [ "$NO_RESTART" = 1 ]; then
    say "Skipping acpid restart (--no-restart)"
  else
    if [ "$DRY_RUN" = 1 ]; then
      say "Would restart acpid"
    else
      if command -v systemctl >/dev/null 2>&1; then
        systemctl restart acpid || {
          echo "Warning: could not restart acpid. Ensure it is installed and running." >&2
        }
      else
        echo "Note: systemctl not found; please restart acpid manually if needed." >&2
      fi
    fi
  fi
}

ensure_hyprland_hooks() {
  local target_user
  target_user="${SUDO_USER:-$(logname 2>/dev/null || echo "${USER:-}")}"
  if [ -z "$target_user" ] || [ "$target_user" = "root" ]; then
    say "Skipping Hyprland hook: unable to determine non-root user context"
    return
  fi

  local target_home
  target_home=$(getent passwd "$target_user" | cut -d: -f6 2>/dev/null || true)
  if [ -z "$target_home" ]; then
    target_home=$(eval echo "~$target_user")
  fi
  if [ -z "$target_home" ]; then
    say "Skipping Hyprland hook: could not resolve home for $target_user"
    return
  fi

  local candidates=(
    "$target_home/.config/hypr/hyprland.conf"
    "$target_home/.config/omarchy/current/theme/hyprland.conf"
  )

  local updated=0
  for conf in "${candidates[@]}"; do
    [ -f "$conf" ] || continue
    if grep -Fq '/etc/acpi/check-lid-on-startup.sh' "$conf"; then
      say "Hyprland hook already present in $conf"
      continue
    fi

    if [ "$DRY_RUN" = 1 ]; then
      say "Would append Hyprland auto-switch hook to $conf"
    else
      say "Appending Hyprland auto-switch hook to $conf"
      run_as_user "$target_user" bash -c "cat <<'EOF' >> '$conf'

# Monitor auto-switch startup hook (managed by install-monitor-auto-switch.sh)
exec-once = /etc/acpi/check-lid-on-startup.sh
exec = /etc/acpi/check-lid-on-startup.sh
EOF"
    fi
    updated=1
  done

  if [ "$updated" -eq 0 ]; then
    say "Note: No Hyprland config files were updated automatically; add the exec hooks manually if needed."
  fi
}

invoke_startup_check() {
  if [ "$DRY_RUN" = 1 ]; then
    say "Would run ${DEST_DIR}/check-lid-on-startup.sh to synchronise layout immediately"
    return
  fi

  if ! command -v pgrep >/dev/null 2>&1; then
    say "pgrep not available; skipping immediate startup lid check"
    return
  fi

  if pgrep -x Hyprland >/dev/null 2>&1; then
    say "Hyprland detected; running ${DEST_DIR}/check-lid-on-startup.sh for immediate layout sync"
    if ! "${DEST_DIR}/check-lid-on-startup.sh"; then
      echo "Warning: ${DEST_DIR}/check-lid-on-startup.sh exited with a non-zero status." >&2
    fi
  else
    say "Hyprland not running; skipping immediate startup lid check"
  fi
}

validate_src() {
  local missing=0
  for f in hypr-utils.sh lid-open.sh lid-close.sh check-lid-on-startup.sh; do
    if [ ! -f "$REPO_ACPI_DIR/$f" ]; then
      echo "Missing: $REPO_ACPI_DIR/$f" >&2
      missing=1
    fi
  done
  if [ "$missing" = 1 ]; then
    echo "Source directory invalid. Use --src DIR to point at the directory containing the ACPI scripts." >&2
    exit 1
  fi
}

main() {
  parse_args "$@"

  # Allow --help without root
  if [ "$DRY_RUN" != 1 ]; then
    need_sudo
  fi

  validate_src
  install_from_repo
  update_events
  post_install
  ensure_hyprland_hooks
  invoke_startup_check

  say "Install complete. You can test with:"
  say "  sudo ${DEST_DIR}/lid-close.sh"
  say "  sudo ${DEST_DIR}/lid-open.sh"
}

main "$@"
EOF

chmod +x scripts/install-monitor-auto-switch.sh

---

Step 3 – Install and enable acpid

sudo pacman -S --needed acpid
sudo systemctl enable --now acpid

Adjust the commands for your distribution if necessary.

---

Step 4 – Deploy the handlers

Run the installer from your workspace:

sudo ~/monitor-auto-switch/scripts/install-monitor-auto-switch.sh

This command:

• Copies the four ACPI scripts into /etc/acpi/ (backing up any modified versions).
• Creates /etc/acpi/events/lid-open and /etc/acpi/events/lid-close with the correct regex triggers.
• Touches /var/log/lid-events.log and sets its permissions to 0666.
• Restarts acpid unless you pass --no-restart.
• Appends Hyprland hooks (exec-once and exec) for /etc/acpi/check-lid-on-startup.sh when a config is found.
• Immediately runs /etc/acpi/check-lid-on-startup.sh if Hyprland is active so the current session matches the real lid/monitor state.

Useful flags:

• -n / --dry-run – preview the actions.
• --src DIR, --dest DIR, --events-dir DIR – override source or destination paths.
• --no-restart – skip the systemctl restart acpid step.

---

Step 5 – Verify the setup

1. Manual triggers

   sudo /etc/acpi/lid-close.sh
   sudo /etc/acpi/lid-open.sh

   Watch journalctl -t lid-events -n 20 (or -f) for messages such as Auto-detected external monitor via sysfs: DP-3.

2. Inspect Hyprland state

   hyprctl -j monitors | jq '.[].{name,focusedMonitor,activeWorkspace}'
   hyprctl -j workspaces | jq '.[] | {id, monitor}'

3. Confirm Hyprland hooks

   grep -n "/etc/acpi/check-lid-on-startup.sh" ~/.config/hypr/hyprland.conf \
       ~/.config/omarchy/current/theme/hyprland.conf 2>/dev/null

4. Check acpid

   systemctl status acpid

---

Step 6 – Everyday usage

• Optional aliases for quick toggles:

  alias external_only='sudo /etc/acpi/lid-close.sh'
  alias dual_display='sudo /etc/acpi/lid-open.sh'
  alias laptop_only='sudo bash -c "source /etc/acpi/hypr-utils.sh && export_hypr_env && set_laptop_only"'

• Live log view while testing hardware:

  journalctl -t lid-events -f --no-pager

• Whenever you change ~/monitor-auto-switch/acpi/hypr-utils.sh, rerun the installer so /etc/acpi stays updated.

---

How it works

• ACPI wiring: acpid listens for button/lid events and executes /etc/acpi/lid-open.sh or /etc/acpi/lid-close.sh.
• Shared helper: /etc/acpi/hypr-utils.sh bridges into the Hyprland session, auto-detects the active DP*/HDMI* connector, applies monitor layouts, moves workspaces, and logs via logger -t lid-events.
• Startup sync: /etc/acpi/check-lid-on-startup.sh runs on Hyprland start/reload to keep layouts consistent even when booting with the lid closed.
• Manual control: The same helpers power the optional aliases so you can reapply layouts without physically touching the lid.

---

Troubleshooting

• External monitor not detected: Check journalctl -t lid-events for auto-detect messages. If the wrong connector is selected, update EXTERNAL_MONITOR (e.g., HDMI-A-1) in hypr-utils.sh and redeploy.
• Hyprland not found: Ensure Hyprland is running (pgrep -x Hyprland). Without it, the scripts fall back to laptop-only.
• System suspends on lid close: Set HandleLidSwitch=ignore in /etc/systemd/logind.conf and consider adding the kernel parameter button.lid_init_state=open.
• Repeated “Another lid handler instance running” messages: Those are from the flock guard—usually harmless. Wait a moment before retriggering.
• No logs at all: Inspect sudo journalctl -u acpid and confirm the event files exist under /etc/acpi/events/.

---

Changelog

• 2025-10-19: Converted the guide into a standalone tutorial with full script listings, documented DP/HDMI auto-detection, and noted that the installer replays the startup sync when Hyprland is active.

Tested on:

• Omarchy v3.1.0
• Arch Linux (kernel 6.17.3-arch2-1)
• Hyprland 0.51.1 (Wayland)
• Lenovo ThinkPad X1 Carbon Gen 12 (21KC0046US)
• Firmware Lenovo N3YET79W (1.44, 2025-06-19)

These scripts should work on other distributions with minor adjustments to package names, service management, or compositor behavior.

[daniellavoie]

Thank you for putting this together. It is thoughful and helpful about learning concepts of the kernel I did not know about.

I have a strong feeling this could be integrated in Omarchy once there is enough feedback from the community.

First, let's create the shared utilities library. I've created a template above in the first artifact (hypr-utils.sh).

Unfortunately, it seems you artifact is not refered or attached to the tutorial. Is that something you could share please ?

[mwaltzer]

How silly, all that attention to the docs and I forgot to include it!

Added in the relevant section.

[daniellavoie]

And which section would you refer as the configuration one ?

Modify the CONFIGURATION SECTION with your values

[mwaltzer]

Made some major updates that should make this more clear. Thank you for the feedback!

[jan-l]

Great tutorial! I'm having some issues with the waybar being duplicated after the computer resumes from sleep/lockscreen. Toggling the bar off and on makes it go back to a single bar but it gets a bit annoying to have to do so often.

Also waking up from sleep often ends up with the external monitor being in a weird resolution which fixes itself if the laptop is opened/closed again, however I've had these weird resolution bugs on the external monitor before using this script for managing the lids so probaly not worth considering an issue with this tutorial.

[mwaltzer]

I observed the double Waybar after I very first initialized the script, but a Hyprland restart fixed it and I've not seen the issue since. I can try to reproduce on my end.

[mwaltzer]

Figured it out!

Remove exec-once = hypridle from hyprlnad.conf from here:

# Edit the managed config
nvim ~/.config/hypr/hyprland.conf

# Add these lines:
exec-once = /etc/acpi/check-lid-on-startup.sh
exec-once = hypridle

I also added some additional measures to make sure it Waybar doesn't launch twice in the docs.

[paulimur-net]

Thanks for this, it's helpful.

I'm running into an issue: when booting without the external monitor connected the laptop display is blank after login. I tried closing and re-opening the lid to trigger the lid open script but it didn't help.

As a workaround I commented out changes to monitors.conf, and have been using the external-only command after startup (or just opening and closing the lid). The lid open and lid close actions are working the way they should.

If someone can make a suggestion for troubleshooting this I'd appreciate it.

As a side note, I wasn't sure in which file(s) and where to put:

sleep 0.6
hypr dispatch focusmonitor "$EXTERNAL_MONITOR"
hypr dispatch workspace 1

so I didn't do that step.

[mwaltzer]

I'll look into this tomorrow and get back to you!

[mwaltzer]

Added a complete installation script to make it easy! It should migrate everything you did and finish what you struggled with. let me know if this works for you.

[gregid]

Curious - does it handle multiple external monitors (i.e. more than one)?

[mwaltzer]

I have not had an opportunity to try this so unfortunately, I don't know!

[docgwiz]

Thank you! I hit two snags that prevented me from completing this project, both due to my inexperience:

Manual installation incomplete because of need to modify systemd bootloader files, which is not something I can do.

Script installation incomplete due to "Source directory invalid" error when running install script.

I'll keep revisiting this project as my knowledge improves.

[RadoslavMuntag]

Thanks this was very helpful.

I managed to set it up manually without much problems except for one major thing and I still can't figure it out.
Don't know if I skipped something important in the tutorial or not.

The exec and exec-once in the hyprland.conf for running the /etc/acpi/check-lid-on-startup.sh runs into an error when executing.

the log:
[/etc/acpi/check-lid-on-startup.sh] Another lid handler instance running, exiting.

After some tests I've realized that it might happen because the exec 9>/run/lid-switch.lock and some other things in the hyper-utils.sh need to be executed as sudo. However the exec and exec-once commands execute it as user.

I also tried the~/install-monitor-auto-switch.sh setup, but the problem persists

UPDATE: I have found an ugly workaround (don't know if should be used)

I used sudo visudo to give my user ability to use sudo only on /etc/acpi/check-lid-on-startup.sh without password.

To do that use:
sudo visudo -f /etc/sudoers.d/some-file-name

Add line:
your-username ALL=(ALL) NOPASSWD: /etc/acpi/check-lid-on-startup.sh

Reboot system or relaunch hyprland

Than refactor in hyprland.conf:
exec-once = /etc/acpi/check-lid-on-startup.sh
exec = /etc/acpi/check-lid-on-startup.sh

To:
exec-once = sudo /etc/acpi/check-lid-on-startup.sh
exec = sudo /etc/acpi/check-lid-on-startup.sh

[mwaltzer]

Major updates that should fix these issues!

[mombe090]

Working like a charm, exactly what i needed today. The litle history i went to librairy to do some stuff, guess what forgot to uncomment my traditionnal way to disable the laptop screen. Thank you for this amazing scripts, hope will be set as default in omarchy.

One thing went reboot while lib is closed, at startup the laptop screen remain disable event when the lib open and waybar is not launch.

[mwaltzer]

Major updates that should fix these issues!

[mwaltzer]

Hi all,

Been working away at perfecting this, but wanted to wait for Omarchy 3.1.0 and its Hyprland changes before publishing them. I hope they they help make your life just a bit easier!

[landsman]

I’d love to see this built into Omarchy by default — it feels natural and expected. Is anyone opposed to that?

[yandy-r]

Thank you for this!

[wyliethomas]

Thank you!!! No issues!

[cmdrrobin]

Thanks for creating this and making it available for others. Is there a reason to update both hyprland.conf in .config and in omarchy folder?

  local candidates=(
    "$target_home/.config/hypr/hyprland.conf"
    "$target_home/.config/omarchy/current/theme/hyprland.conf"
  )

[Bucurenciu-Cristian]

Hi everyone, I wanted to tell you about this software:

hyprdynamic

This has solved my problem and it's working perfectly.

[cmdrrobin]

Yes! I have installed it yesterday and works perfectly. This will fit nicely with Omarchy setup. (in my opinion...)

I'm a single monitor guy and was finding a good solution for it when I work on my laptop or if I dock it and want to use an external display.

For those who are interested in, dotfiles - hyprdynamicmonitors

UPDATE: keep in mind, my omarchy dotfiles are not 100% perfect yet. Still need some TLC

[saidbenmoumen]

man this is perfect! thanks a lot! (hyprdynamicmonitors)
this worked many things for me i needed from monitors modes (dual, external_only, laptop_only, ..) switching
to even some battery niceties like switching from 60hz -> 120hz & vice versa based on ac_adapter or battery...