hypreyes

Ephemeral Hyprland monitor profile manager. Switch between monitor configurations without touching your config file. Changes are applied at runtime via hl.monitor and revert on next Hyprland reload.

Features

• Save and switch named monitor profiles
• Quick layouts (side-by-side, stacked, mirrored, primary-only, grid) generated from live monitor state
• Visual layout diagrams — see where each monitor lands before you apply
• Confirm/revert prompt after every apply, with a 15s auto-revert if you can't see the screen to answer
• Type-to-filter profile and layout lists
• Full TUI and CLI — all actions available both ways
• Config stored in ~/.config/hypreyes/profiles.yaml
• Default profile seeded from live state on first run; cannot be deleted

Requirements

• Hyprland 0.55+ (uses hyprctl eval with hl.monitor Lua API)
• Go 1.21+

Install

Direct install with Go (no clone needed):

go install github.com/archlemon/hypreyes@latest

Installs to $GOPATH/bin (usually ~/.local/go/bin or ~/go/bin).

From source:

git clone https://github.com/archlemon/hypreyes.git
cd hypreyes
make install          # installs to ~/.local/bin
make install PREFIX=/usr/local

Or build and run without installing:

git clone https://github.com/archlemon/hypreyes.git
cd hypreyes
make build
./hypreyes

TUI

Launch with no arguments:

hypreyes

Profile list

Key	Action
↑↓ / jk	Navigate
g / G	Jump to first / last
/	Filter by name (Esc clears, Enter keeps the filter and returns to the list)
Enter	Apply selected profile
n	New profile (from live state, opens editor)
s	Snapshot live state → open in editor
S	Quick save — prompt for name, save immediately
e	Edit selected profile
r	Rename selected profile
d	Delete selected profile
l	Open quick layouts
?	Toggle full help
q	Quit

The highlighted profile is drawn as a to-scale diagram showing where each monitor sits, so you can tell Side-by-Side from Stacked at a glance. Disabled and mirrored monitors are listed beneath the diagram rather than drawn, since they take up no space in the virtual desktop.

Quick layouts

Key	Action
↑↓ / jk	Navigate layouts
/	Filter layouts by name, key or description
Enter	Apply selected layout
Tab	Select a monitor to tweak
+ / -	Step the selected monitor's scale through common presets
s	Type an exact scale for the selected monitor
m	Cycle the selected monitor's resolution/refresh mode
Esc	Back

Tweaks (scale, mode) apply to the pending layout only — positions recompute immediately, and nothing changes on screen until you apply a layout. Handy when you plug in an external monitor that needs a different scale than your main one: Tab to it, bump the scale, then apply Side-by-Side.

Layouts are generated from the current live monitor state. For two monitors: Side-by-Side (both directions), Stacked (both directions), Primary (each monitor), Mirror (both directions). For three or more: Row, Column, Grid, and one Primary layout per monitor.

Confirm screen

Shown after every apply. Default selection is Revert.

Key	Action
←→ / hl / Tab	Toggle Keep/Revert
Enter	Confirm selection
y	Keep the new layout
n / Esc	Revert to previous state

A countdown runs for 15 seconds. If it reaches zero the previous layout is restored automatically — the case this protects against is applying a layout that leaves you with no readable screen to answer the prompt on.

Edit profile

Navigate with Tab / ↑↓. Press Enter on a monitor to edit its settings. Ctrl+S saves.

The name field is a real text input: arrow keys, Home/End and paste all work, and letters such as j, k and q type normally instead of being read as navigation. A live diagram below the monitor list updates as you edit, and overlapping monitors are flagged before you save.

In monitor edit, ↑↓ on Resolution scrolls through available modes reported by Hyprland. All other fields accept direct text input and reject values that aren't valid (a non-numeric scale, a transform outside 0–3) instead of silently discarding them.

CLI

# Print the version
hypreyes version

# List connected monitors
hypreyes monitors

# Profile management
hypreyes profile list
hypreyes profile apply "Work"
hypreyes profile save "Work"       # snapshot live state; overwrites if name exists
hypreyes profile delete "Gaming"

# Quick layouts
hypreyes layout list
hypreyes layout apply side-by-side-right
hypreyes layout apply stacked-down
hypreyes layout apply mirror-dp-4-right-hdmi-a-1

# Override a monitor's scale before the layout is computed (repeatable)
hypreyes layout apply side-by-side-right --scale HDMI-A-1=1.5
hypreyes layout apply row-right --scale HDMI-A-1=1.5 --scale DP-1=1.25

Multi-word names work without quoting in most shells but quotes are recommended.

Config file

Profiles are saved as YAML. Location search order:

1. ~/.config/hypreyes/profiles.yaml
2. ~/hypreyes-profiles.yaml
3. ./hypreyes-profiles.yaml

Example:

profiles:
  - name: Default
    monitors:
      - name: DP-4
        resolution: 3840x2560
        refresh_rate: 119.99
        x: 0
        y: 0
        scale: 1.6
        transform: 0
      - name: HDMI-A-1
        resolution: 2560x1440
        refresh_rate: 144.0
        x: 2400
        y: 0
        scale: 1.6
        transform: 0
  - name: Laptop only
    monitors:
      - name: DP-4
        resolution: 3840x2560
        refresh_rate: 119.99
        x: 0
        y: 0
        scale: 1.6
      - name: HDMI-A-1
        disabled: true
  - name: Mirror
    monitors:
      - name: DP-4
        resolution: 3840x2560
        refresh_rate: 119.99
        x: 0
        y: 0
        scale: 1.6
      - name: HDMI-A-1
        mirror: DP-4

Makefile

make          # build
make test     # run tests
make install  # install to ~/.local/bin
make lint     # vet + staticcheck
make clean

How it works

Applies changes via hyprctl eval 'hl.monitor({...})' — Hyprland's Lua runtime API. This bypasses the config parser so your hyprland.conf or .lua config is never modified. Changes persist until Hyprland reloads its config or hypreyes reverts them.

Mirroring requires a two-step apply: clear the mirror first (mirror=""), then set the new mode and position. hypreyes handles this automatically.