How to Remap Buttons on Logitech Devices with OpenLogi: A Complete Guide

OpenLogi remaps Logitech mouse buttons through a TOML configuration file, CLI commands, or a GUI application, converting physical button events into logical ButtonId values that trigger customizable actions ranging from keystrokes to application launches.

OpenLogi is an open-source tool that enables advanced button remapping for Logitech peripherals on desktop systems. Whether you want to bind the Back button to a browser navigation command or transform the middle click into a custom shortcut, OpenLogi provides multiple interfaces to remap buttons on Logitech devices with precise control over the input pipeline.

Configuring Button Remaps via TOML

OpenLogi stores per-device bindings in a plain-text TOML file located at ~/.config/openlogi/config.toml. Each device entry contains a bindings table that maps a ButtonId to an Action, as defined in the repository's configuration schema.

To remap buttons, locate your device section (identified by receiver ID and slot) and modify the bindings table:

[devices."receiver:12345678:slot:1"]
enabled = true
dpi = 800
bindings = {
    Back    = "BrowserBack",
    Forward = { CustomShortcut = "Cmd+Shift+P" },
    MiddleClick = { OpenApplication = { path = "~/Downloads", display_name = "Downloads" } }
}

The configuration supports multiple action types including simple clicks, custom shortcuts, and application launches. Changes to this file trigger an immediate reload of the agent, ensuring your mappings apply without restarting the application.

Remapping via the CLI

The openlogi-cli crate provides scriptable control over button mappings. Located at crates/openlogi-cli/src/main.rs, the CLI implements list and set-binding commands for device management.

First, identify your device:

openlogi-cli list

Then apply a binding:

openlogi-cli set-binding \
  --device "receiver:12345678:slot:1" \
  --button Back \
  --action BrowserBack

This command updates the underlying TOML configuration and signals the agent to reload, providing a programmatic alternative to manual file editing.

Programmatic Remapping with Rust

For custom tooling, OpenLogi's Rust API exposes direct binding manipulation through the DesktopState struct in crates/openlogi-desktop/src/state/bindings.rs.

use openlogi_core::binding::{ButtonId, Action};
use openlogi_desktop::state::DesktopState;

// Assume `state` is a mutable reference to the running DesktopState
let device_key = "receiver:12345678:slot:1";
state
    .config
    .set_binding(device_key, ButtonId::Back, Action::BrowserBack);
state.persist_and_reload("binding");

The set_binding method updates the in-memory configuration, while persist_and_reload writes the change to disk and notifies the agent. This approach is useful for building custom automation tools that dynamically adjust mappings based on context.

Remapping via the GUI

The OpenLogi desktop application provides a visual interface for button remapping. The GUI writes atomically to the configuration file and maintains backup copies to prevent data loss.

To remap a button using the GUI:

1. Open the OpenLogi desktop app and select your Logitech mouse from the device list.
2. Navigate to the Bindings tab and locate the button identifier (e.g., MiddleClick).
3. Select the desired action type, such as OpenApplication or CustomShortcut.
4. Fill in the required parameters (e.g., path ~/Downloads for an application launch).
5. Click Save to write the changes to config.toml and apply them immediately via the IPC mechanism in crates/openlogi-ipc/src/ipc.rs.

Understanding the Remapping Pipeline

Under the hood, OpenLogi implements button remapping through a layered architecture that enforces Logitech device specificity and logical button abstraction.

Device Detection and Filtering

The hook subsystem in crates/openlogi-hook receives raw mouse events from the operating system. Only Logitech devices are considered remappable, enforced by the source_is_remappable function in crates/openlogi-hook/src/lib.rs (lines 90-101). This ensures the remapping logic only processes events from supported hardware.

Logical Button Resolution

All button identifiers are unified under the ButtonId enum defined in crates/openlogi-core/src/binding/button.rs. This enum includes variants such as LeftClick, RightClick, MiddleClick, Back, Forward, and DpiToggle.

When the agent receives a button event, the bindings_for_current function in crates/openlogi-desktop/src/state/bindings.rs (lines 102-108) looks up the current device's bindings map. The system then dispatches the associated action to the inject subsystem, which synthesizes the appropriate mouse or keyboard event at the OS level.

Persistence and Live Reload

The configuration system supports atomic writes and live reloading. When you edit the TOML file or use the GUI/CLI, the agent reloads the configuration instantly without requiring a restart. The GUI specifically writes atomically and maintains backup copies to ensure configuration integrity.

Summary

• OpenLogi stores button mappings in ~/.config/openlogi/config.toml using a TOML structure that maps ButtonId values to Action types.
• The CLI (openlogi-cli) provides list and set-binding commands for scriptable remapping of Logitech devices.
• The Rust API exposes set_binding and persist_and_reload methods in DesktopState for programmatic control.
• Only Logitech devices pass the source_is_remappable filter in the hook subsystem, ensuring targeted remapping.
• Changes apply immediately through the IPC transport system without requiring agent restarts.

Frequently Asked Questions

Where is the OpenLogi configuration file stored?

The default location is ~/.config/openlogi/config.toml on Unix-like systems. This plain-text TOML file contains per-device settings including DPI values and button bindings tables. You can edit this file manually or through the GUI/CLI interfaces.

Can I remap buttons on non-Logitech mice?

No. The hook subsystem in crates/openlogi-hook/src/lib.rs specifically filters for Logitech devices using the source_is_remappable function (lines 90-101). Only hardware identified as Logitech peripherals will trigger the remapping logic.

Do I need to restart the agent after changing button mappings?

No. OpenLogi supports live configuration reloading. When you modify the TOML file or use the GUI/CLI to update bindings, the agent detects the change and applies it immediately via the IPC transport mechanism in crates/openlogi-ipc/src/ipc.rs.

What button actions are supported besides mouse clicks?

OpenLogi supports several action types defined in the core crate: BrowserBack, BrowserForward, CustomShortcut (for key combinations), OpenApplication (to launch programs), and standard mouse events like LeftClick or MiddleClick. The full schema is documented in docs/CONFIGURATION.md.

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