How to Configure Custom Keyboard Shortcuts in OpenLogi's TOML Files

OpenLogi stores user configuration in plain TOML files where custom keyboard shortcuts are defined using the CustomShortcut variant of the Action enum, parsed as human-readable chords like "Cmd+Shift+P" and assigned to device bindings, per-app overrides, Action Ring slots, or global keyboard mappings.

OpenLogi is an open-source input management framework that translates mouse buttons and device inputs into system-level keyboard events. Understanding how custom keyboard shortcuts configured in OpenLogi's TOML files work allows you to inject complex key combinations directly from your hardware without application-level scripting.

The CustomShortcut Action Type

At the core of OpenLogi's shortcut system is the Action enum defined in crates/openlogi-core/src/binding/action.rs. The CustomShortcut variant wraps a KeyCombo struct, representing a specific chord of modifier keys and a character key that the system will simulate when the action is triggered.

When the TOML parser encounters a binding definition, it deserializes entries like CustomShortcut = "Cmd+Shift+P" into Action::CustomShortcut(KeyCombo). This abstraction ensures that any input source—whether a mouse button, gesture, or another keyboard shortcut—can emit the same standardized key event through OpenLogi's injection layer.

How KeyCombo Parses Shortcut Strings

The human-readable chord syntax is handled by the KeyCombo parser located in crates/openlogi-core/src/binding/key_combo.rs. This module splits strings on the + delimiter to identify modifier flags and the final key code.

Valid modifier tokens include Cmd, Ctrl, Shift, and Option (macOS nomenclature). The parser validates these against macOS key codes at configuration time, rejecting invalid combinations before the runtime injection phase begins. According to the AprilNEA/OpenLogi source code, Windows-specific key mappings are processed in separate platform layers rather than in the core TOML parsing logic.

TOML Configuration Contexts for Shortcuts

OpenLogi supports defining custom keyboard shortcuts configured in OpenLogi's TOML files across four distinct binding contexts. Each context determines which input triggers the simulated keystroke and under what conditions the action executes.

Device-Level Bindings

Device bindings attach shortcuts directly to physical controls on a specific mouse or input device. These mappings live under the [devices."<device-id>".bindings] section and override default button behaviors.

[devices."receiver:aabbccdd:slot:1".bindings]
MiddleClick = { CustomShortcut = "Ctrl+Space" }

In this example, pressing the middle mouse button on the specified device injects a Ctrl+Space keystroke into the active application.

Per-Application Overrides

Per-app bindings allow the same physical button to emit different shortcuts depending on which application currently has focus. These tables use the syntax [devices."<device-id>".per_app_bindings."<app-identifier>"].

[devices."receiver:aabbccdd:slot:1".per_app_bindings."exe:sharex.exe"]
MiddleClick = { CustomShortcut = "F1" }

This configuration maps the middle mouse button to the F1 key exclusively when ShareX is the foreground window, reverting to default behavior in other contexts.

Action Ring Integration

The Action Ring provides a radial menu interface where each slot can trigger a custom shortcut. Slots are defined under [devices."<device-id>".action_ring.default.slots] and require both an action and an icon specification.

[devices."receiver:aabbccdd:slot:1".action_ring.default.slots]
Right = { action = { CustomShortcut = "Cmd+Shift+P" }, icon = "Applications" }

Here, selecting the right slot from the Action Ring injects the Cmd+Shift+P chord, commonly used to open application launchers or command palettes.

Global Keyboard Bindings

Global bindings map key combinations on the physical keyboard itself to OpenLogi actions, independent of any mouse device. These reside in [keyboard.bindings] and reference action identifiers directly.

[keyboard.bindings]
"shift+command+f5" = "ShowDesktop"

While this example triggers the built-in ShowDesktop action, the same syntax supports any defined action within the OpenLogi system, including custom shortcuts when referenced by identifier.

Complete Configuration Examples

The repository includes a comprehensive reference at docs/config.example.toml demonstrating production-ready patterns. Below are four distinct patterns for custom keyboard shortcuts configured in OpenLogi's TOML files:

# 1. Assign a custom shortcut to the middle mouse button of a specific device

[devices."receiver:aabbccdd:slot:1".bindings]
MiddleClick = { CustomShortcut = "Ctrl+Space" }

# 2. Override the same button only when ShareX is the active app

[devices."receiver:aabbccdd:slot:1".per_app_bindings."exe:sharex.exe"]
MiddleClick = { CustomShortcut = "F1" }

# 3. Add a custom shortcut to the Action Ring (right slot)

[devices."receiver:aabbccdd:slot:1".action_ring.default.slots]
Right = { action = { CustomShortcut = "Cmd+Shift+P" }, icon = "Applications" }

# 4. Define a global keyboard shortcut (Shift+Cmd+F5) that shows the desktop

[keyboard.bindings]
"shift+command+f5" = "ShowDesktop"

Implementation Deep Dive

Several source files govern how TOML-defined shortcuts translate into system events:

• docs/config.example.toml: Provides the authoritative reference for valid TOML structures and nesting conventions.
• crates/openlogi-core/src/binding/action.rs: Defines the Action enum including the CustomShortcut variant and its serialization logic.
• crates/openlogi-core/src/binding/key_combo.rs: Implements the parser for chord syntax and validates macOS key code compatibility.
• crates/openlogi-desktop/src/ui/action.rs: Handles rendering of custom shortcut labels and icons in the graphical configuration interface.
• crates/openlogi-inject/src/inject/*.rs: Contains platform-specific implementations for injecting the parsed key events into the operating system event queue.

Summary

• OpenLogi uses TOML files for user configuration, with shortcuts defined as CustomShortcut tables containing KeyCombo strings.
• The chord syntax uses + to separate modifiers (Cmd, Ctrl, Shift, Option) from the final key, parsed by crates/openlogi-core/src/binding/key_combo.rs.
• Shortcuts can be bound at the device level, per-application, within the Action Ring, or as global keyboard mappings.
• The Action::CustomShortcut enum variant in crates/openlogi-core/src/binding/action.rs provides the runtime representation used across all binding types.
• Platform-specific injection logic in the openlogi-inject crate translates these configurations into actual OS key events at runtime.

Frequently Asked Questions

What is the correct syntax for modifier keys in OpenLogi shortcuts?

OpenLogi accepts Cmd, Ctrl, Shift, and Option as modifier tokens in the chord string. These must be separated by the + character and precede the final key code, as implemented in crates/openlogi-core/src/binding/key_combo.rs. For example, "Cmd+Shift+P" represents holding Command and Shift while pressing P.

Can custom keyboard shortcuts be used on Windows, or are they macOS-only?

While the KeyCombo parser in crates/openlogi-core/src/binding/key_combo.rs validates macOS key codes during TOML parsing, the actual platform injection is handled in crates/openlogi-inject/src/inject/*.rs. This architecture allows Windows-specific mappings to be processed separately, though the TOML configuration syntax remains identical across platforms.

Where should I define a shortcut that needs to work everywhere versus only in specific apps?

Use [keyboard.bindings] for global shortcuts that should trigger regardless of input device or application focus. Use [devices."<id>".bindings] for hardware-specific mappings, and [devices."<id>".per_app_bindings."<exe>"] for context-sensitive overrides that only apply when a specific application is focused.

How does OpenLogi validate that my shortcut string is valid?

Validation occurs at configuration load time in crates/openlogi-core/src/binding/key_combo.rs. The parser attempts to resolve the chord string into a KeyCombo struct containing modifier flags and a key code. If the syntax is malformed or contains invalid key names, the TOML parser will fail during initialization, preventing runtime errors in the injection layer.

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