How to Configure Gesture Bindings in OpenLogi: A Complete Guide

OpenLogi stores gesture bindings in a plain-text TOML file where you map swipe directions to named actions inside device-specific [devices."<physical-key>".bindings] tables.

To configure gesture bindings in OpenLogi, you edit the application's TOML configuration—typically located at ~/.config/openlogi/config.toml—to define direction-based actions for gesture-enabled buttons on your Logitech devices. Unlike simple button mappings, gesture bindings use a nested structure that assigns distinct actions to up, down, left, and right swipes, which the application parses at runtime through the DeviceConfig struct in crates/openlogi-core/src/config.rs.

Where Gesture Bindings Are Stored

OpenLogi uses a hierarchical TOML format for all peripheral settings. The configuration schema is documented in docs/CONFIGURATION.md (lines 66-83), with gesture-specific metadata appearing at line 82 and device-key handling described in the "Shape" section (lines 39-45).

Before editing, locate your platform-specific config path:

• Linux: ~/.config/openlogi/config.toml
• macOS: ~/Library/Application Support/openlogi/config.toml
• Windows: %APPDATA%\openlogi\config.toml

Gesture bindings reside inside the [devices."<physical-key>".bindings] table, where <physical-key> is your device's unique identifier (e.g., receiver:1234:slot:2).

Configuring Gesture Bindings

Follow these steps to map swipe directions to actions for any gesture-enabled button.

Step 1: Locate Your Device Configuration

Identify or create the device entry using the physical device key reported by OpenLogi. This key follows the format receiver:<id>:slot:<number>:

[devices."receiver:1234:slot:2"]
enabled = true
custom_name = "MX Master 3"
dpi = 1200

Step 2: Define the Gesture Map

Create a bindings subtable for your device. Use the button's logical name (e.g., Button3 for the gesture button on MX Master mice) as the key, and supply a gesture table containing the four direction keys:

[devices."receiver:1234:slot:2".bindings]
Button3 = {
    gesture = {
        up    = "VolumeUp",
        down  = "VolumeDown",
        left  = "Back",
        right = "Forward"
    }
}

Each direction must contain a valid action name string. These names correspond to action definitions elsewhere in your configuration file.

Step 3: Save and Reload

Save the file. OpenLogi watches the configuration file for changes and reloads automatically without requiring a restart, as implemented in the configuration parsing logic within crates/openlogi-core/src/config.rs.

Disabling Specific Gesture Directions

You can selectively disable swipe directions for an entire device using the disabled_gestures array. Add this field directly inside the device table (not the bindings subtable):

[devices."receiver:1234:slot:2"]
disabled_gestures = ["left", "right"]

This prevents left and right swipes from generating any actions across all gesture buttons on that device, effectively freeing those directions for system-level shortcuts.

Complete Configuration Example

Here is a full working example based on config.example.toml that demonstrates proper structure alongside other device settings:

[devices."receiver:1234:slot:2"]
custom_name = "My MX Master 3"
enabled = true
dpi = 1200
thumbwheel_sensitivity = 14
disabled_gestures = ["left", "right"]

[devices."receiver:1234:slot:2".bindings]
Button3 = {
    gesture = {
        up    = "Copy",
        down  = "Paste",
        left  = "Back",
        right = "Forward"
    }
}

In this configuration, swiping up on Button3 triggers the Copy action, while swiping down triggers Paste. The disabled_gestures entry ensures left and right swipes are ignored entirely for this device.

Summary

• OpenLogi configures gesture bindings through TOML files located in your system's config directory.
• Bindings live inside [devices."<physical-key>".bindings] tables using button logical names like Button3.
• The gesture subtable maps up, down, left, and right directions to named action strings.
• Use the disabled_gestures array in the device table to suppress specific directions device-wide.
• Configuration parsing and validation occur in crates/openlogi-core/src/config.rs via the DeviceConfig struct.

Frequently Asked Questions

How do I find the correct physical device key for my Logitech device?

The physical device key follows the format receiver:<receiver-id>:slot:<slot-number> and appears in OpenLogi's logs when you connect a peripheral. You can retrieve it by running OpenLogi with verbose logging enabled, then use that exact string—including quotes—inside your TOML device tables, as documented in docs/CONFIGURATION.md (lines 66-83).

Can I use different gesture bindings for different devices?

Yes. Each device has its own [devices."<physical-key>"] table with an isolated bindings subtable. Configure Button3 with different gesture maps in each device block, and OpenLogi will apply the correct mappings based on which device is currently active, according to the implementation in crates/openlogi-core/src/config.rs.

What action names are valid for gesture directions?

Valid action names are the same strings used for standard button bindings throughout OpenLogi. These typically include actions like Copy, Paste, VolumeUp, VolumeDown, Back, and Forward. Refer to the Actions section in docs/CONFIGURATION.md for the complete list of supported action strings recognized by the DeviceConfig parser.

How do I disable gestures only on specific buttons rather than the entire device?

Currently, OpenLogi supports disabling gestures at the device level using the disabled_gestures array in the device table (documented at line 82 of docs/CONFIGURATION.md). To disable a specific direction on a single button, simply omit that direction from the button's gesture map—only defined directions will trigger actions, while undefined directions effectively perform no operation on that specific button.

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