Crate kbd_global 

Global hotkey runtime for kbd on Linux.

kbd-global wraps the pure matching engine from kbd in a threaded runtime that owns device discovery, hotplug handling, and command-based registration APIs. It reads from evdev devices directly, so it works on Wayland, X11, and TTY without display-server integration.

Quick start

use kbd::hotkey::{Hotkey, Modifier};
use kbd::key::Key;
use kbd_global::manager::HotkeyManager;

let manager = HotkeyManager::new()?;

let _guard = manager.register(
    Hotkey::new(Key::C).modifier(Modifier::Ctrl).modifier(Modifier::Shift),
    || println!("fired"),
)?;

HotkeyManager is the main entry point. Registration returns a BindingGuard that keeps the binding alive — drop it to unregister. Key types, actions, and layer definitions come from kbd.

Layers

Layers let you swap between different binding sets at runtime:

use kbd::action::Action;
use kbd::key::Key;
use kbd::layer::Layer;
use kbd_global::manager::HotkeyManager;

let manager = HotkeyManager::new()?;

let layer = Layer::new("vim-normal")
    .bind(Key::J, || println!("down"))?
    .bind(Key::K, || println!("up"))?;

manager.define_layer(layer)?;
manager.push_layer("vim-normal")?;

Layers stack — the most recently pushed layer is checked first. See kbd::layer for oneshot, swallow, and timeout options.

Architecture

HotkeyManager sends typed commands to a dedicated engine thread over a channel, using an eventfd wake mechanism to interrupt poll(). All mutable runtime state lives in the engine thread.

+------------------+                +------------------+
|  HotkeyManager   | -- commands -->|  Engine thread   |
| (command sender) |<--- replies ---|   (event loop)   |
+------------------+                +------------------+
                                             |
                                             v
                                  poll(devices + wake_fd)

Create a manager with HotkeyManager::new() or HotkeyManager::builder(), register bindings, and keep the returned guards alive. Dropping a guard unregisters its binding; dropping the manager stops the runtime.

Backend selection

Currently only Backend::Evdev is available. It reads /dev/input/event* directly and requires permission to access Linux input devices:

sudo usermod -aG input $USER

Use the builder for explicit backend selection or grab mode:

use kbd_global::backend::Backend;
use kbd_global::manager::HotkeyManager;

let manager = HotkeyManager::builder()
    .backend(Backend::Evdev)
    .build()?;

Feature flags

Feature	Effect
grab	Exclusive device capture via EVIOCGRAB with uinput forwarding for unmatched events
serde	Adds Serialize/Deserialize to shared key and hotkey types via kbd

Current limitations

• Linux only
• evdev is the only backend
• Action::EmitHotkey and Action::EmitSequence are not yet implemented in the runtime

See also

• kbd — core dispatch engine, key types, and layer logic
• kbd-evdev — low-level device backend used by this crate

Modules

backend

Input backends for the global runtime.

binding_guard

BindingGuard keeps a registered binding alive.

error

Error types for the kbd-global runtime.

manager

HotkeyManager — the public API entry point.