- macOS — primary. Modern (14+) initially; older support is best-effort.
- Linux — secondary. X11 + Wayland under common compositors (GNOME, KDE, sway/Hyprland).
global-hotkey registers Shift+Space at startup. The combo is
configurable in Settings → Global and re-registered live.
If macOS prompts for input-monitoring or accessibility permission, grant it
once — High Beam itself doesn't need it (the global-hotkey crate operates
without entitlements on modern macOS), but some AppleScript-driven Core
built-ins (sleep / restart) may.
There is no portable global-hotkey API on Wayland (the spec doesn't include
one; the GlobalShortcuts portal's coverage varies by compositor). High Beam
punts: bind highbeam --open in your WM / DE keyboard settings. The same
mechanism works on X11, so we don't have to maintain a separate X path.
highbeam --open returns immediately if a daemon is running; otherwise it
starts one and opens the window. So the moving parts are:
- A long-lived
highbeamprocess — installed packages register a user-level systemd unit (/usr/lib/systemd/user/highbeam.service) for this.systemctl --user enable --now highbeam.serviceafter install. - A WM keybind that invokes
highbeam --opento summon the window.
GNOME — Settings → Keyboard → View and Customize Shortcuts → Custom
Shortcuts → +:
| Name | Command | Shortcut |
|---|---|---|
| High Beam | highbeam --open |
Super+Space |
KDE Plasma — System Settings → Shortcuts → Custom Shortcuts → Edit →
New → Global Shortcut → Command/URL. Trigger = Super+Space,
Command = highbeam --open.
sway — add to ~/.config/sway/config:
bindsym $mod+space exec highbeam --open
…then reload (swaymsg reload or $mod+Shift+c).
Hyprland — add to ~/.config/hypr/hyprland.conf:
bind = SUPER, SPACE, exec, highbeam --open
For anything else, check the WM's own keybind docs — the pattern is always
"bind a key to run the highbeam --open shell command".
highbeam --open from the CLI is the canonical way to summon the window on
Linux, so the daemon needs single-instance semantics. Implementation: unix
domain socket.
- macOS:
~/Library/Application Support/high-beam/high-beam.sock - Linux:
$XDG_RUNTIME_DIR/high-beam.sock(falls back to$XDG_STATE_HOME/high-beam/high-beam.sockwhen the runtime dir is unset)
First instance binds and listens; subsequent invocations connect, send a
command (open\n), and exit. The wire format is intentionally tiny —
newline-terminated ASCII commands.
If a previous daemon crashed and left a stale socket behind, the next start detects it (connect fails) and replaces it.
| Purpose | macOS | Linux |
|---|---|---|
Config (settings.toml) |
~/Library/Application Support/high-beam/ |
$XDG_CONFIG_HOME/high-beam/ |
| Themes | ~/Library/Application Support/high-beam/themes/ |
$XDG_CONFIG_HOME/high-beam/themes/ |
| Plugins | ~/Library/Application Support/high-beam/plugins/ |
$XDG_DATA_HOME/high-beam/plugins/ |
| Plugin cache | ~/Library/Caches/high-beam/plugins/<name>/ |
$XDG_CACHE_HOME/high-beam/plugins/<name>/ |
| Frecency DB | ~/Library/Application Support/high-beam/frecency.sqlite |
$XDG_DATA_HOME/high-beam/frecency.sqlite |
| Per-plugin log | <plugin_dir>/plugin.log |
<plugin_dir>/plugin.log |
Resolved via the directories crate. Parent directories are created lazily
on first write.
The Core built-in's sleep / restart / shut-down actions run via
osascript; macOS may prompt for automation permission the first time
High Beam tries to control Finder / System Events. Grant once.
Plugins that use highbeam:system.applescript will likewise need the
relevant automation entitlements granted to High Beam.
App-launching (highbeam:actions.openUrl against a .app path, or the
example app-launcher plugin) doesn't need any entitlement.
No special permissions. Plugins that run subprocesses via
highbeam:system.exec or use highbeam:actions.exec rely on whatever
PATH the daemon was started with.
Packaging recipes and code-signing setup are in docs/distribution.md. No auto-updater in v1.