Global Keyboard Remapping in OpenLogi: Supported Modifiers and Syntax

OpenLogi supports four modifiers for global keyboard remapping: shift, control (alias ctrl), option (alias alt), and command (alias cmd), which can be combined in any order with a base key using the mod+key syntax.

Understanding the exact modifiers available for global keyboard remapping in OpenLogi is essential for creating effective hotkey configurations. This guide covers the complete modifier set, their aliases, parsing behavior, and practical usage based on the official source code in the AprilNEA/OpenLogi repository.

Supported Modifiers in OpenLogi

OpenLogi defines global keyboard remapping triggers through the KeyModifiers struct in crates/openlogi-core/src/config/key_trigger.rs (lines 22-30). The implementation recognizes four modifier keys:

Modifier	Description	Accepted Aliases
shift	Shift key held	—
control	Control key held	ctrl
option	Option/Alt key held	alt
command	Command (⌘) key held	cmd

These modifiers are mutually combinable. You can specify any subset from zero modifiers (bare key) up to all four simultaneously.

Trigger String Syntax

OpenLogi parses modifier specifications from textual trigger strings following the pattern [modifier+]*+key. The parser:

1. Splits the string on + delimiters
2. Matches each modifier segment against valid names and aliases
3. Rejects unknown modifiers with a parse error (lines 41-44)

Valid trigger examples:

• "f5" — bare F5 key
• "shift+f2" — Shift+F2 combination
• "ctrl+alt+f1" — Control+Option+F1 using aliases
• "shift+cmd+f5" — Shift+Command+F5

Case sensitivity follows the implementation in KeyTrigger::from_str (lines 36-41).

Practical Code Examples

Creating a Keyboard Configuration with Modifiers

use openlogi_core::config::{KeyTrigger, KeyboardConfig};
use openlogi_core::binding::Action;

// Simple F5 binding with no modifiers
let mut cfg = KeyboardConfig::default();
cfg.bindings.insert(
    "f5".parse::<KeyTrigger>().unwrap(),
    Action::LaunchApplication { 
        path: "/Applications/Calculator.app".into() 
    },
);

// Complex modifier combination: Shift+Command+F2
cfg.bindings.insert(
    "shift+cmd+f2".parse::<KeyTrigger>().unwrap(),
    Action::RunCommand { 
        command: "osascript -e 'tell application \"Safari\" to reload'".into() 
    },
);

Parsing and Inspecting Modifier Masks

let trigger: KeyTrigger = "ctrl+alt+f1".parse()
    .expect("valid trigger");

// Access individual modifier flags
assert!(trigger.modifiers.control);
assert!(trigger.modifiers.option);
assert!(!trigger.modifiers.shift);
assert!(!trigger.modifiers.command);

// Verify the base keycode
assert_eq!(trigger.keycode, 0x7A); // F1 scan code

Runtime Modifier Inspection

let mods = trigger.modifiers;

println!(
    "Active modifiers — Shift: {}, Control: {}, Option: {}, Command: {}",
    mods.shift, mods.control, mods.option, mods.command
);

Key Source Files and Exports

File Path	Purpose
crates/openlogi-core/src/config/key_trigger.rs	Defines KeyModifiers struct, implements parsing logic, documents supported modifier names
crates/openlogi-core/src/config/config.rs	Re-exports KeyModifiers and KeyTrigger for public API consumption
docs/CONFIGURATION.md	Describes TOML configuration syntax for end users

Modifier Limitations and Error Handling

OpenLogi enforces strict validation during trigger parsing. Any unrecognized modifier produces a parse failure rather than silent ignore. This prevents configuration errors from creating unexpected behavior.

The alias system provides flexibility—control and ctrl are equivalent—while maintaining a canonical internal representation. When serializing configurations, OpenLogi uses the full canonical names (control, option, command) rather than aliases.

Summary

• Four modifiers support global keyboard remapping in OpenLogi: shift, control/ctrl, option/alt, and command/cmd
• Syntax: Combine modifiers with + delimiters ending in the base key (e.g., "shift+cmd+k")
• Implementation: Defined in KeyModifiers struct at crates/openlogi-core/src/config/key_trigger.rs
• Validation: Unknown modifiers trigger parse errors; aliases are accepted during input parsing
• Combinations: Multiple modifiers stack arbitrarily; zero modifiers valid for bare key bindings

Frequently Asked Questions

Can I use Windows/Super key as a modifier in OpenLogi?

No. The KeyModifiers struct in OpenLogi only defines the four macOS-oriented modifiers (shift, control, option, command). There is no dedicated Windows or Super key modifier in the current implementation. Cross-platform support would require extending the modifier mask definition in key_trigger.rs.

What happens if I misspell a modifier name?

OpenLogi returns a parse error. The FromStr implementation for KeyTrigger validates each modifier segment against the known set and rejects unknown strings (lines 41-44). This strict validation ensures configuration errors surface immediately rather than causing silent binding failures.

Are modifier order and case significant in trigger strings?

Modifier order is flexible—"shift+cmd+k" and "cmd+shift+k" parse identically. However, case sensitivity depends on the specific parser implementation. The source uses direct string matching, so lowercase is recommended for consistency with the documented examples.

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