What Is OpenLogi? A Complete Guide to the Local-First Logitech Options+ Replacement

OpenLogi is a native, local-first replacement for Logitech Options+ written in Rust that provides cross-platform device management, button remapping, and advanced input customization through a three-process architecture.

OpenLogi is an open-source project hosted at AprilNEA/OpenLogi that eliminates cloud dependencies while delivering deeper hardware control than proprietary alternatives. Unlike Logitech's official software, OpenLogi keeps all configuration data on your local machine and exposes every feature through both a graphical interface and a comprehensive CLI.

Architecture: The Three-Process Design

OpenLogi splits functionality across three distinct processes that communicate over a versioned, append-only tarpc/bincode socket defined in crates/openlogi-ipc/AGENTS.md. This separation ensures the input hook remains responsive even when the GUI is closed.

GUI Process

The GUI is a GPUI-based client that presents the configuration interface and manages the Actions Ring overlay. Located in crates/openlogi-desktop, this process handles user interactions while delegating actual device control to the background agent.

Agent Process

The Agent is the headless background server that owns the OS-level input hook and manages all hardware communication. According to the source in crates/openlogi-agent/src/main.rs, this binary sets up a single-instance guard and exposes an IPC surface for other processes. It talks directly to Logitech devices over HID++ or UVC protocols and orchestrates device I/O through crates/openlogi-agent-core/src/lifecycle.rs.

Overlay Process

The Overlay is a lightweight IPC client that draws the cursor-centered Actions Ring interface. This separate process ensures the overlay renders smoothly without blocking the main configuration window.

Core Capabilities and Features

OpenLogi supports Logitech mice, keyboards, and webcams connected via Logi Bolt, Unifying receiver, Bluetooth, or wired connections. Battery levels and charge states are exposed for all supported peripherals.

Button remapping operates through an OS-level input hook implemented in crates/openlogi-hook, allowing assignment of any action—including custom shortcuts, scripts, or push-to-talk chords—to any button with independent short/long-press handling.

Additional capabilities include:

• Per-app profiles – Automatic profile switching based on the focused application (macOS and Windows; Linux on X11/XWayland)
• Lighting control – RGB management on supported keyboards with hex color, brightness, and temperature adjustment
• DPI management – Presets, cycle actions, and direct DPI setting via HID++ 0x2201
• SmartShift wheel – Enable/disable SmartShift, set sensitivity, and configure the permanent-ratchet panel via HID++ 0x2111
• Gestures – Bind per-direction gestures to capable buttons with live capture
• Actions Ring – An eight-slot cursor-centered overlay for quick actions triggered by ShowActionsRing
• Camera control – Full UVC control (zoom, focus, exposure, color) for Logitech webcams with automatic LED control

Project Structure and Crate Organization

The repository is organized as a Rust workspace with specialized crates defined in the repository's AGENTS.md file. Each crate has a specific responsibility:

• crates/openlogi – CLI wrapper entry point
• crates/openlogi-core – Pure types, TOML config, device models, and locale negotiation (no I/O)
• crates/openlogi-device-registry – Registry of receiver protocols and driver metadata
• crates/openlogi-hidpp – Vendored HID++ protocol implementation
• crates/openlogi-device – Device-layer enumeration, probing, and HID++ communication
• crates/openlogi-hid – Host-specific transport (async-hid, Input Monitoring, probe cache)
• crates/openlogi-assets – Device-render registry and asset fetching
• crates/openlogi-hook – OS-level input capture (CGEventTap, evdev+uinput, WH_MOUSE_LL)
• crates/openlogi-inject – OS-level input synthesis (CGEvent, uinput+MPRIS, SendInput)
• crates/openlogi-agent-core – Shared orchestration for hook runtime, DPI cycling, and Actions Ring state
• crates/openlogi-ipc – Tarpc contract used for GUI↔agent communication
• crates/openlogi-ui – GPUI code shared by the desktop app and overlay

CLI and Configuration Workflow

All configuration lives in a single plain-text TOML file that can be synced across machines. The openlogi CLI provides scripting and debugging capabilities as documented in docs/USAGE.md.

Common CLI operations include:

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

You can bind actions programmatically:

openlogi bind <device> <button> my_custom

Configuration is loaded programmatically through crates/openlogi-core. The following pattern appears in crates/openlogi/src/main.rs and the agent initialization:

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 are defined in the TOML configuration file:

[actions.my_custom]
type = "shell"
command = "notify-send 'Hello from OpenLogi!'"

Key Source Files and Entry Points

Understanding the codebase structure helps when contributing or debugging:

• crates/openlogi/src/main.rs – Entry point for the openlogi CLI binary
• crates/openlogi-agent/src/main.rs – Starts the headless agent, sets up the single-instance guard and IPC server
• crates/openlogi-ui/src/lib.rs – Core UI library used by both the desktop app and the overlay
• crates/openlogi-agent-core/src/lifecycle.rs – Orchestrates device I/O, hook runtime, and IPC handling
• crates/openlogi-ipc/AGENTS.md – Defines the tarpc IPC contract shared by GUI and agent
• docs/USAGE.md – CLI usage guide and quick-start examples
• README.md – High-level description, feature list, and installation instructions

Summary

• OpenLogi is a local-first, native Rust replacement for Logitech Options+ that runs on macOS, Linux, and Windows
• The three-process architecture (GUI, Agent, Overlay) ensures responsive input handling through tarpc/bincode IPC
• Deep hardware control includes HID++ device management, UVC camera controls, DPI cycling, and RGB lighting
• Flexible configuration uses a single TOML file with full CLI support for scripting and automation
• Modular crate structure separates concerns between device protocols, OS-specific hooks, and UI components

Frequently Asked Questions

How does OpenLogi differ from Logitech Options+?

OpenLogi operates entirely locally without cloud dependencies or telemetry, whereas Logitech Options+ requires account creation and internet connectivity for many features. Additionally, OpenLogi exposes lower-level hardware controls through HID++ and UVC protocols and provides a scriptable CLI interface that the official software lacks.

Which Logitech devices are compatible with OpenLogi?

OpenLogi supports mice, keyboards, and webcams connected via Logi Bolt, Unifying receiver, Bluetooth, or wired connections. Device support is implemented through the crates/openlogi-device and crates/openlogi-hidpp crates, with the device registry maintaining metadata for receiver protocols. Battery level reporting and advanced features like SmartShift require specific HID++ protocol support.

How do the GUI and Agent processes communicate?

The processes communicate over a versioned, append-only tarpc/bincode socket defined in crates/openlogi-ipc/AGENTS.md. This IPC contract allows the GUI to request device operations while the Agent maintains exclusive ownership of the input hook and hardware connections, ensuring the input system remains responsive even if the GUI crashes or closes.

Can I use OpenLogi without the graphical interface?

Yes. The openlogi-agent binary runs as a headless background service that manages all hardware functionality. You can control the agent entirely through the openlogi CLI commands defined in docs/USAGE.md, edit the TOML configuration directly, or build custom frontends that speak the tarpc IPC protocol.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}