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

> Discover OpenLogi, the local-first Rust replacement for Logitech Options+. Gain cross-platform device management, button remapping, and advanced input customization.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: getting-started
- Published: 2026-08-29

---

**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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/USAGE.md).

Common CLI operations include:

```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

```

You can bind actions programmatically:

```bash
openlogi bind <device> <button> my_custom

```

Configuration is loaded programmatically through `crates/openlogi-core`. The following pattern appears in [`crates/openlogi/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi/src/main.rs) and the agent initialization:

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

```toml
[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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi/src/main.rs) – Entry point for the `openlogi` CLI binary
- [`crates/openlogi-agent/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent-core/src/lifecycle.rs) – Orchestrates device I/O, hook runtime, and IPC handling
- [`crates/openlogi-ipc/AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/AGENTS.md) – Defines the tarpc IPC contract shared by GUI and agent
- [`docs/USAGE.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/USAGE.md) – CLI usage guide and quick-start examples
- [`README.md`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/USAGE.md), edit the TOML configuration directly, or build custom frontends that speak the tarpc IPC protocol.