diff --git a/README.md b/README.md
index cb74977..1a032d7 100644
--- a/README.md
+++ b/README.md
@@ -73,6 +73,24 @@ pixelpass <ticket>
 # then run the printed mpv command in another terminal
 ```
 
+### Graphical (optional)
+
+A small window front-end is available in builds compiled with the `gui`
+feature (see [Build](#build)):
+
+```sh
+pixelpass --gui
+```
+
+Host: pick quality / max-viewers / options, click **Start hosting**, and the
+share code appears with a copy button alongside a live viewer count. View:
+paste a code, pick mpv or VLC, click **Connect** and the player launches.
+
+The window is a thin driver — it runs the same headless `pixelpass` as a
+child process and reads its event stream, so the GUI is purely additive and
+the capture machinery is untouched by it. On a build without the feature,
+`--gui` prints a hint to rebuild with it.
+
 ## Requirements
 
 - Linux (Wayland or X11; the backend is autodetected)
@@ -119,6 +137,14 @@ cargo build --release
 
 `rustc` 1.95+ / edition 2024.
 
+The optional graphical front-end (`pixelpass --gui`) is behind a default-off
+cargo feature so the headless build stays lean (it pulls the egui/eframe
+windowing stack). Build it with:
+
+```sh
+cargo build --release --features gui
+```
+
 ## How it works
 
 ```