# What is OpenLogi? A Local-First Rust Replacement for Logitech Options+ > Discover OpenLogi, a local-first Rust alternative to Logitech Options+. Configure devices, remap buttons, and control gestures for your Logitech peripherals without cloud reliance. Get full control today. - Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi) - Tags: getting-started - Published: 2026-08-28 --- **OpenLogi is a native, local-first replacement for Logitech Options+ written in Rust that provides device configuration, button remapping, and gesture control for Logitech peripherals without cloud dependencies.** Unlike proprietary alternatives that require internet connectivity and cloud accounts, OpenLogi keeps your device configuration entirely local. It runs natively on macOS, Linux, and Windows, offering granular control over Logitech mice, keyboards, and webcams through a modular, open-source architecture. ## Architecture and Core Components OpenLogi employs a three-process architecture designed for separation of concerns and system stability. According to the project's [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md) specification, these processes communicate over a versioned, append-only tarpc/bincode socket defined in [`crates/openlogi-ipc/AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/AGENTS.md). ### The GUI Process The **GUI** is a GPUI-based client that presents the configuration interface and the **Actions Ring** overlay. This process handles all user-facing interaction while delegating device control to the background agent. ### The Agent Process The **Agent** is a headless background server that owns the OS-level input hook and manages direct communication with Logitech devices over HID++ or UVC protocols. It exposes an IPC surface for the GUI and maintains the single-instance guard implemented in [`crates/openlogi-agent/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/main.rs). ### The Overlay Process The **Overlay** is a lightweight IPC client that draws the cursor-centered Actions Ring. This dedicated process ensures the overlay renders smoothly without interfering with the main configuration window. ## Project Structure and Crate Organization The repository is organized as a Rust workspace with specialized crates handling distinct responsibilities. As documented in the source code structure: - **`crates/openlogi`** – CLI wrapper and entry point at [`src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/src/main.rs) - **`crates/openlogi-core`** – Pure types, TOML configuration parsing, device models, and action catalogs (zero I/O) - **`crates/openlogi-device`** – Device-layer enumeration, probing, and HID++ write operations - **`crates/openlogi-hidpp`** – Vendored HID++ protocol implementation for Logitech device communication - **`crates/openlogi-hook`** – OS-level input capture using platform-specific APIs: CGEventTap on macOS, evdev+uinput on Linux, and WH_MOUSE_LL on Windows - **`crates/openlogi-inject`** – OS-level input synthesis via CGEvent (macOS), uinput+MPRIS (Linux), and SendInput (Windows) - **`crates/openlogi-agent-core`** – Shared orchestration logic including hook runtime, DPI cycling, and Actions Ring state management in [`src/lifecycle.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/src/lifecycle.rs) - **`crates/openlogi-ui`** – Core UI library shared between the desktop application and overlay ## Key Features and Capabilities OpenLogi provides comprehensive hardware control through direct protocol implementation rather than proprietary drivers. **Device Support** – Full compatibility with Logitech mice, keyboards, and webcams connected via Logi Bolt, Unifying receiver, Bluetooth, or wired connections. Battery levels and charge states are exposed through the device registry. **Button Remapping** – The OS-level input hook in `crates/openlogi-hook` allows assignment of any action (custom shortcuts, shell scripts, or push-to-talk chords) to any button, with independent handling for short and long presses. **Per-Application Profiles** – Automatic profile switching based on the focused application is supported on macOS and Windows, with Linux support for X11 and XWayland environments. **Advanced Hardware Control** – Direct access to HID++ registers enables DPI management (presets and cycle actions via HID++ 0x2201), SmartShift wheel configuration (HID++ 0x2111), and RGB lighting control with hex color and temperature adjustment. **Gestures and Actions Ring** – Bind per-direction gestures to capable buttons with live capture, or invoke the eight-slot cursor-centered Actions Ring overlay through the `ShowActionsRing` action. **Camera Control** – Full UVC protocol implementation provides zoom, focus, exposure, and color control for Logitech webcams, including automatic LED management. ## Configuration and CLI Usage All configuration lives in a single plain-text TOML file that can be version-controlled and synced across machines. The `openlogi` CLI provides scripting and debugging capabilities as documented in [`docs/USAGE.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/USAGE.md). Common CLI operations: ```bash openlogi list # show paired devices openlogi assets sync # pre-fetch device renders openlogi diag dpi # quick DPI smoke-test openlogi diag lighting ff0000 # set a wired RGB keyboard to solid red ``` ## Programmatic Integration You can interact with OpenLogi's configuration system programmatically. The following Rust example demonstrates loading the TOML configuration with proper error handling and locale activation: ```rust use openlogi_core::config::Config; use tracing::info; fn main() { // Initialise logging (the agent and GUI both call this) openlogi_agent::logging::init(); // Load the user's TOML config, falling back to defaults on error let cfg = Config::load_or_default().unwrap_or_else(|e| { info!("failed to read config: {} – using defaults", e); Config::default() }); // Activate the locale before any UI is built openlogi_core::locale::activate(cfg.app_settings.language.as_deref()); } ``` Custom actions can be defined directly in the TOML configuration: ```toml [actions.my_custom] type = "shell" command = "notify-send 'Hello from OpenLogi!'" ``` Once defined, bind the action via the CLI: ```bash openlogi bind