Integration

Wire hyprpilot into your compositor: keybinds, autostart, the tray icon. Examples below cover Hyprland and Sway — both ride the same hyprpilot ctl surface.

Keybinds

The recommended chord flips the overlay on and off:

# Hyprland — ~/.config/hypr/hyprland.conf
bind = SUPER, space, exec, hyprpilot ctl overlay toggle

# Sway — ~/.config/sway/config
bindsym $mod+space exec hyprpilot ctl overlay toggle

Mash the keybind as fast as you like — the overlay always lands in a sensible visible/hidden state.

Subcommands worth binding

# Show + focus the overlay (no-op when already visible).
hyprpilot ctl overlay present

# Show + focus a specific instance in one chord.
hyprpilot ctl overlay present --instance <uuid>

# Hide. Webview stays warm; next show is instant.
hyprpilot ctl overlay hide

# Flip.
hyprpilot ctl overlay toggle

Push-to-talk pattern

Pipe text into hyprpilot ctl prompts send from anywhere — voice transcription, clipboard, scratchpad — and the overlay fires the prompt:

# Hyprland — dump a voice transcription into the focused instance
bind = SUPER, grave, exec, whisper-stream | hyprpilot ctl prompts send --stdin

The same shape works with wl-paste, xsel, xdotool, or any program that emits text on stdout. A simple "send my clipboard as a prompt":

bindsym $mod+v exec wl-paste | hyprpilot ctl prompts send --stdin

Autostart

The AUR package installs a systemd user unit at /usr/lib/systemd/user/hyprpilot.service. Enable it once:

systemctl --user enable --now hyprpilot.service

The shipped unit isn't bound to any session target — start condition is yours to compose. To tie it to your graphical session, see the systemd note in the installation guide. Pairs with [daemon.window] visible = false (the default) so the daemon boots hidden and your keybind is the first user-visible map.

If you'd rather start it inline in your compositor config, wrap it so env vars come in:

# Hyprland
exec-once = bash -lc 'hyprpilot daemon'

# Sway
exec bash -lc 'hyprpilot daemon'

The cross-platform [autostart] enabled = true config knob registers an XDG autostart entry — that's the GNOME / KDE / macOS / Windows path. wlroots compositors (Hyprland, Sway) ignore XDG autostart, so use the systemd unit or exec-once there.

Tray icon

The daemon installs a system tray icon at boot:

• Left-click — toggle overlay.
• Right-click → Toggle / Show / Hide overlay — same as the ctl overlay subcommands.
• Right-click → Shut down — clean shutdown.

If your compositor has no tray support, the daemon logs a warning and continues without one — the keybind and ctl paths still work.

CLI escape hatch

Running hyprpilot (no subcommand) a second time, against a daemon that's already up, pops the overlay forward instead of starting a new daemon. Handy when nothing's bound yet:

hyprpilot       # first call — starts the daemon
hyprpilot       # second call — toggles overlay