monitor-lets-go

Lightweight, reliable daemon for automatic monitor layout switching on Linux Wayland.

Plugs into your dock — external monitors turn on, built-in turns off. Unplug — built-in comes back. No black screens, no manual hyprctl commands, no bash scripts.

---

Features

• Zero black screens — three safety layers: compositor socket events, polling fallback, systemd watchdog with 1-second restart
• Atomic layout application — writes a config file, calls hyprctl reload — no intermediate broken states
• Shell hooks — restart waybar, change wallpapers, run any script after mode switch
• Single binary — one Go binary, one YAML config, one systemd unit
• 3.5 MB stripped — no runtime dependencies beyond the compositor itself
• Extensible — Backend interface makes adding new compositors trivial

---

How it works

┌──────────────────┐     socket2 events     ┌──────────────────┐
│   Hyprland        │──────────────────────▶│   monitor-lets-go daemon  │
│   compositor      │  monitoradded/removed │                  │
│                   │                       │  debounce 1200ms  │
│  hyprctl reload ◀─┤──────────────────────│  determine state   │
│  (reads monitors  │                       │  apply layout     │
│   .conf file)     │                       │  run hooks        │
└──────────────────┘                       └──────┬───────────┘
                                                  │
                                           ┌──────▼───────────┐
                                           │   systemd         │
                                           │   watchdog 30s    │
                                           │   restart 1s      │
                                           └──────────────────┘

1. Startup — daemon queries connected monitors, determines portable/docked, applies layout
2. Hotplug events — listens to compositor socket for monitoradded/monitorremoved
3. Debounce — waits 1200ms after the last event (docks fire multiple events)
4. Apply — writes monitors.conf, calls hyprctl reload (atomic)
5. Hooks — runs shell commands after layout change (waybar, wallpapers, etc.)
6. Fallback polling — every 5s checks monitor state (catches missed events)

Safety guarantees

#	Guarantee
1	Never apply 0 monitors — layout is rejected if all monitors are disabled
2	Never disable built-in without externals — docked mode verified before applying
3	Crash recovery — systemd restarts in 1s, daemon re-evaluates state on startup
4	Hang recovery — systemd watchdog kills and restarts if daemon freezes
5	Graceful shutdown — optionally restores portable layout on SIGTERM
6	Socket reconnect — exponential backoff if compositor socket drops
7	Atomic writes — temp file + rename prevents config corruption

---

Installation

Prerequisites

• Hyprland compositor (other compositors: see Extending)
• Go 1.21+ (build only, no Go needed at runtime)
• systemd user instance (for the service)

Build

git clone https://github.com/mat/monitor-lets-go.git
cd monitor-lets-go
make build          # → monitor-lets-go (3.5 MB stripped)
make install        # → ~/.local/bin/monitor-lets-go
make systemd-install # → enable & start systemd user service

Hyprland config setup

Add one line to ~/.config/hypr/hyprland.conf (or hyprland.lua):

source = ~/.config/hypr/monitors.conf

Remove any static monitor=... lines — monitor-lets-go manages monitors now.

Then reload:

hyprctl reload

---

Configuration

Create ~/.config/monitor-lets-go/config.yaml:

# Backend selection: "auto" (recommended), "hyprland"
backend: auto

# Quiet period after the last hotplug event (docks fire multiple events)
debounce: 1200ms

# Fallback polling interval (0 = disable)
poll_interval: 5s

# Restore portable layout on daemon shutdown
restore_on_exit: true

# External monitors that trigger docked mode.
# Plain name: matches connector (DP-1, HDMI-A-1).
# desc: prefix: matches by monitor description (survives port rename).
external:
  - DP-9
  - DP-10
  - desc:Dell Inc. DELL U2723QE

# Monitor layouts for each mode.
# "portable" and "docked" are required.
modes:
  portable:
    monitors:
      - name: eDP-1
        enabled: true
        mode: preferred        # auto-detect best resolution
        position: "0x0"
        scale: 1.0

  docked:
    monitors:
      - name: DP-10
        enabled: true
        mode: "2560x1440@165"
        position: "0x0"
        scale: 1.0
      - name: DP-9
        enabled: true
        mode: "3440x1440@120"
        position: "2560x0"
        scale: 1.0
      - name: eDP-1
        enabled: false          # turn off laptop screen when docked

# Shell commands run after a layout change.
# Commands run concurrently, failures are logged but never crash the daemon.
# Tildes (~) and $HOME are expanded.
hooks:
  on_dock:
    - "killall waybar; waybar &"
    - "wallpapers"
  on_undock:
    - "wallpapers"

Monitor matching

Two match modes in the external list:

Syntax	Matches	Use case
DP-1	Exact connector name	Simple setups
desc:Dell U2723QE	Substring in monitor description	Survives port rename across different docks

Run hyprctl monitors all to see your monitor names and descriptions.

Backend-specific configuration

Use the backend_config section for compositor-specific options:

backend_config:
  output_path: ~/.config/hypr/custom-monitors.conf   # override generated config path

Hyprland keys:

Key	Type	Default	Description
output_path	string	~/.config/hypr/monitors.conf	Path to the generated monitor config file. Supports ~ expansion.

The deprecated top-level output_path key still works — backend_config takes priority if both are set.

When adding new compositor backends, their options go into the same backend_config section without changing the core config structure.

Hook commands

Hooks are shell commands executed via sh -c. Each command gets a 30-second timeout. Commands run in parallel — one slow hook won't block others.

Examples:

hooks:
  on_dock:
    - "systemctl --user restart waybar"
    - "~/.config/monitor-lets-go/on-dock.sh"
    - "notify-send 'Docked' 'External monitors active'"

---

Usage

Manual

monitor-lets-go -config ~/.config/monitor-lets-go/config.yaml

systemd (recommended)

# Install and start
make systemd-install

# Check status
systemctl --user status monitor-lets-go

# View logs
journalctl --user -u monitor-lets-go -f

# Restart
systemctl --user restart monitor-lets-go

# Disable
systemctl --user disable --now monitor-lets-go

Verify it's working

1. Connect your dock
2. Check logs: journalctl --user -u monitor-lets-go -f
3. You should see: state changed state=docked and your hooks running
4. Disconnect the dock
5. You should see: state changed state=portable

---

Architecture

monitor-lets-go/
├── cmd/monitor-lets-go/main.go           # Entry point: CLI, systemd watchdog, backend registry
├── internal/
│   ├── backend/
│   │   ├── interface.go          # Backend interface + types (MonitorInfo, Event, State)
│   │   └── hyprland.go           # Hyprland: hyprctl + socket2 .socket2.sock
│   ├── config/config.go          # YAML parse, validate, defaults, monitor matching
│   ├── daemon/daemon.go          # Event loop, debounce, state machine, safety checks
│   └── hook/hook.go              # Shell hook runner with timeouts
├── contrib/monitor-lets-go.service       # systemd user unit
├── monitor-lets-go.example.yaml          # Annotated config example
├── Makefile
└── go.mod

Key interfaces

Backend — the only compositor-dependent code:

type Backend interface {
    Name() string
    GetMonitors(ctx context.Context) ([]MonitorInfo, error)
    ApplyLayout(ctx context.Context, monitors []MonitorConfig) error
    Events(ctx context.Context) (<-chan Event, <-chan error)
    Close() error
}

Dependencies

Only one external dependency: gopkg.in/yaml.v3. Everything else is Go standard library.

---

Extending

Adding a new compositor (Sway, KDE, etc.)

1. Create internal/backend/<name>.go implementing the Backend interface
2. Register the factory in cmd/monitor-lets-go/main.go:resolveBackend()
3. That's it — the daemon auto-detects or uses the configured backend

Example skeleton for Sway:

// internal/backend/sway.go
package backend

type swayBackend struct { logger *slog.Logger }

func NewSway(logger *slog.Logger, opts map[string]any) (Backend, error) {
    // Check if SWAYSOCK is set and swaymsg is available
    // opts carries backend_config from the config file
    return &swayBackend{logger: logger}, nil
}

func (s *swayBackend) Name() string { return "sway" }

func (s *swayBackend) GetMonitors(ctx context.Context) ([]MonitorInfo, error) {
    // swaymsg -t get_outputs → parse JSON → []MonitorInfo
}

func (s *swayBackend) ApplyLayout(ctx context.Context, monitors []MonitorConfig) error {
    // swaymsg output <name> mode <mode> pos <x> <y> scale <s>
}

func (s *swayBackend) Events(ctx context.Context) (<-chan Event, <-chan error) {
    // sway IPC socket (SWAYSOCK) → subscribe to output events
}

func (s *swayBackend) Close() error { return nil }

Then register in main.go:

backends := []struct { ... }{
    {"hyprland", backend.NewHyprland},
    {"sway", backend.NewSway},           // ← add this line
}

---

Troubleshooting

"No compositor backend available"

Hyprland is not running or HYPRLAND_INSTANCE_SIGNATURE is not set. Make sure monitor-lets-go starts after Hyprland (the systemd unit uses After=graphical-session.target).

"source file not found" on hyprctl reload

The source = ~/.config/hypr/monitors.conf line must be added to hyprland.conf. The daemon creates this file on first run.

Hooks not running

Check the hook command works from a terminal first. Hooks run via sh -c, so shell syntax like &&, ;, pipes work. Each hook has a 30-second timeout.

Monitor names changed after reboot

Use desc: prefix matching instead of connector names. Run hyprctl monitors all to find the description string.

external:
  - desc:Dell Inc. DELL U2723QE   # survives port rename

---

License

MIT