361 lines
12 KiB
Markdown
361 lines
12 KiB
Markdown
# 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 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 config file + calls reload (Hyprland), or sends batch swaymsg commands (Sway) — 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
|
|
- **Multi-compositor** — works with Hyprland and Sway out of the box
|
|
|
|
---
|
|
|
|
## How it works
|
|
|
|
```
|
|
┌─ Hyprland: socket2 .socket2.sock ──────┐
|
|
compositor ───┤ ├──▶ monitor-lets-go daemon
|
|
└─ Sway: i3 IPC $SWAYSOCK ────────────┘ │
|
|
hotplug events │
|
|
┌───────────────────────────────
|
|
│ debounce 1200ms
|
|
│ determine state (portable/docked)
|
|
│ apply layout
|
|
│ 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 monitor connect/disconnect events
|
|
3. **Debounce** — waits 1200ms after the last event (docks fire multiple events)
|
|
4. **Apply** — Hyprland: writes `monitors.conf` + `hyprctl reload`; Sway: `swaymsg 'output ...'` batch commands
|
|
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 config writes (Hyprland)** — temp file + rename prevents config corruption |
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
### Prerequisites
|
|
|
|
- **Hyprland** or **Sway** compositor (other compositors: see [Extending](#extending))
|
|
- **Go 1.21+** (build only, no Go needed at runtime)
|
|
- **systemd** user instance (for the service)
|
|
|
|
### Build
|
|
|
|
```bash
|
|
git clone https://github.com/Wakatron/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
|
|
```
|
|
|
|
### Choosing a backend
|
|
|
|
Configure `backend` in `config.yaml`:
|
|
|
|
| Value | Behavior |
|
|
|-------|----------|
|
|
| `auto` (recommended) | Probes Hyprland first, falls back to Sway |
|
|
| `hyprland` | Force Hyprland backend |
|
|
| `sway` | Force Sway backend |
|
|
|
|
### Hyprland 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:
|
|
|
|
```bash
|
|
hyprctl reload
|
|
```
|
|
|
|
### Sway setup
|
|
|
|
No Sway config changes required — the daemon applies monitor layouts directly via `swaymsg` commands.
|
|
|
|
For systemd integration (so the daemon can reach Sway when launched as a service), add to your Sway config:
|
|
|
|
```
|
|
exec systemctl --user import-environment SWAYSOCK WAYLAND_DISPLAY XDG_CURRENT_DESKTOP
|
|
```
|
|
|
|
Verify monitors are detected:
|
|
|
|
```bash
|
|
swaymsg -t get_outputs
|
|
```
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
Create `~/.config/monitor-lets-go/config.yaml`:
|
|
|
|
```yaml
|
|
# Backend selection: "auto" (recommended), "hyprland", or "sway"
|
|
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:
|
|
- desc:Dell Inc. DELL U2723QE
|
|
- DP-9
|
|
- DP-10
|
|
|
|
# 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: desc:Xiaomi Corporation Mi Monitor 3440x1440
|
|
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:
|
|
- "wallpapers"
|
|
on_undock:
|
|
- "wallpapers"
|
|
```
|
|
|
|
### Monitor matching
|
|
|
|
Two match modes, supported in both the `external` list and the `modes` section:
|
|
|
|
| Syntax | Matches | Use case |
|
|
|---|---|---|
|
|
| `DP-1` | Exact connector name | Simple setups, built-in displays |
|
|
| `desc:Dell U2723QE` | Substring in monitor description | Survives port rename across different docks |
|
|
|
|
Sway description format: `make model serial_widthxheight` (with serial omitted if `Unknown`).
|
|
Run `hyprctl monitors all` (Hyprland) or `swaymsg -t get_outputs` (Sway) to see your monitor names and descriptions.
|
|
|
|
**desc: in modes** — when a monitor name in `modes` uses the `desc:` prefix, the daemon resolves it to the actual connector name at runtime. Ambiguous matches (a desc matching multiple monitors) cause an error.
|
|
|
|
### Backend-specific configuration
|
|
|
|
Use the `backend_config` section for compositor-specific options:
|
|
|
|
```yaml
|
|
backend_config:
|
|
output_path: ~/.config/hypr/custom-monitors.conf # override generated config path
|
|
```
|
|
|
|
| Backend | Key | Type | Default | Description |
|
|
|---------|-----|------|---------|-------------|
|
|
| Hyprland | `output_path` | string | `~/.config/hypr/monitors.conf` | Path to the generated monitor config file. Supports `~` expansion. |
|
|
| Sway | _(none)_ | — | — | Layout is applied via `swaymsg` commands directly — no config files needed. |
|
|
|
|
The deprecated top-level `output_path` key still works — `backend_config` takes priority if both are set.
|
|
|
|
### 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:
|
|
|
|
```yaml
|
|
hooks:
|
|
on_dock:
|
|
- "systemctl --user restart waybar"
|
|
- "~/.config/monitor-lets-go/on-dock.sh"
|
|
- "notify-send 'Docked' 'External monitors active'"
|
|
```
|
|
|
|
---
|
|
|
|
## Usage
|
|
|
|
### Manual
|
|
|
|
```bash
|
|
monitor-lets-go -config ~/.config/monitor-lets-go/config.yaml
|
|
```
|
|
|
|
### systemd (recommended)
|
|
|
|
```bash
|
|
# 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: `layout applied state=docked` and your hooks running
|
|
4. Disconnect the dock
|
|
5. You should see: `layout applied 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
|
|
│ │ └── sway.go # Sway: swaymsg + i3 IPC socket ($SWAYSOCK)
|
|
│ ├── 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:
|
|
|
|
```go
|
|
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
|
|
|
|
1. Create `internal/backend/<name>.go` implementing the `Backend` interface (see `interface.go`)
|
|
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
|
|
|
|
See `internal/backend/sway.go` for a full implementation reference: monitor detection via subprocess, layout application via batch commands, hotplug events via raw IPC socket with exponential reconnection backoff, and `desc:` name resolution for connector-name-portability.
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### "No compositor backend available"
|
|
|
|
The daemon couldn't find any supported compositor.
|
|
|
|
**Hyprland:** `HYPRLAND_INSTANCE_SIGNATURE` is not set. Make sure monitor-lets-go starts **after** Hyprland (the systemd unit uses `After=graphical-session.target`). Verify with: `echo $HYPRLAND_INSTANCE_SIGNATURE`.
|
|
|
|
**Sway:** `SWAYSOCK` is not set and no sway IPC socket found in `$XDG_RUNTIME_DIR`. Make sure Sway is running and the socket is accessible. Verify with: `ls $XDG_RUNTIME_DIR/sway-ipc.*.sock`.
|
|
|
|
### "source file not found" (Hyprland only)
|
|
|
|
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. This survives port renames across different docks and reboots.
|
|
|
|
**Hyprland:** `hyprctl monitors all` to see descriptions.
|
|
**Sway:** `swaymsg -t get_outputs` to see names, make/model, serial, and native resolution.
|
|
|
|
```yaml
|
|
external:
|
|
- desc:Dell Inc. DELL U2723QE # survives port rename
|
|
|
|
modes:
|
|
docked:
|
|
monitors:
|
|
- name: desc:Dell Inc. DELL U2723QE # also works here
|
|
enabled: true
|
|
```
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
MIT
|