What Is the Role of openlogi-agent-core in OpenLogi? A Deep Dive into the Headless Orchestration Layer

openlogi-agent-core serves as the permanent, headless orchestration layer that manages raw input capture, hardware communication, and state persistence for the OpenLogi background agent without any GUI dependencies.

The openlogi-agent-core crate forms the backbone of the AprilNEA/OpenLogi project's architecture, functioning as the dedicated background process that handles all low-level hardware interactions. This Rust-based module operates entirely without graphical components, enabling continuous operation while keeping the GUI process lightweight and free from blocking I/O operations.

Core Responsibilities of the Headless Agent

The crate manages four critical functions that require uninterrupted background execution to ensure responsive peripheral control.

Input Hook Runtime

The agent runs platform-specific input capture mechanisms directly within the core process. On macOS, it utilizes CGEventTap, while Linux implementations leverage evdev/uinput. These hooks monitor raw device events continuously without blocking or depending on GUI frameworks, ensuring that input capture survives GUI restarts or crashes.

Background HID++ Device Control

All device-side communication executes within the agent, including DPI adjustments, button lighting changes, and battery status queries. By isolating these heavy I/O operations from the GUI process, the system prevents interface lag during intensive hardware transactions. The hardware abstraction layer in crates/openlogi-agent-core/src/hardware.rs provides high-level helpers for these operations.

DPI Cycle State Management

The module maintains persistent state for cycling through user-configured DPI steps. As implemented in crates/openlogi-agent-core/src/dpi.rs, the DpiCycleState struct tracks current settings and transitions between predefined sensitivity levels, ensuring that DPI changes persist across application restarts.

Actions Ring Session State

Timing and state machines for the on-screen Actions Ring—the circular menu triggered by modifier keys—are maintained here. The action_ring module in crates/openlogi-agent-core/src/action_ring.rs handles session lifecycle and input routing while the GUI merely renders the visual representation based on state sent via IPC.

Module Architecture and Key Components

The public API, documented in crates/openlogi-agent-core/src/lib.rs, exposes several high-level modules that compose the orchestration layer:

• orchestrator – The top-level component defined in src/orchestrator.rs that wires together watchers, runtimes, and the main event loop
• watchers – Platform-specific observers for keyboard, mouse, and host-switch events located in src/watchers/keyboard.rs and related subdirectories
• runtime/button – Button-press handling implementation in src/runtime/button.rs that processes physical input events and maps them to actions
• event_monitor – Abstraction layer for normalizing raw input events across macOS and Linux platforms
• hardware – High-level helpers for battery status queries and device metadata retrieval
• capture_plan – Logic determining which inputs trigger specific actions based on user-defined binding maps

Integration with the OpenLogi Ecosystem

The agent communicates with the GUI process through the IPC contract defined in the openlogi-ipc crate. This separation allows the heavyweight GPUI stack to remain unloaded until the user opens the interface, while the agent maintains continuous control of input and device paths.

Pure data structures shared between both processes—including binding maps, device ordering, and timing helpers—reside in the openlogi-core crate. This architectural boundary, referenced in the project's AGENTS.md, ensures that the GUI can be restarted or updated without disrupting active input hooks or hardware connections.

Practical Implementation Examples

Creating and running a minimal orchestrator:

use openlogi_agent_core::orchestrator::Orchestrator;
use openlogi_agent_core::runtime::button::ButtonRuntime;

// Build a minimal orchestrator (in real code you would configure watches, DPI, etc.)
let mut orch = Orchestrator::new();
// Register a button runtime that prints a message on click
orch.register_runtime(ButtonRuntime::new(|_event| {
    println!("Button pressed!");
}));

// Run the orchestrator – this blocks while the background agent operates
orch.run();

Managing DPI cycles programmatically:

use openlogi_agent_core::{DpiCycleState, DpiCycles};

let cycles = DpiCycles::new(vec![800, 1600, 2400]); // user-defined DPI steps
let mut state = DpiCycleState::new(cycles);

// Cycle to the next DPI (e.g., on a DPI-button press)
state.next(); // now at 1600 DPI
println!("Current DPI: {}", state.current());

Summary

• openlogi-agent-core acts as the permanent background process handling all low-level input and hardware operations in OpenLogi.
• The crate maintains GUI-free operation to ensure continuous input capture and device control without loading graphical frameworks.
• Key components include the Orchestrator for event coordination, watchers for platform-specific input monitoring, and dedicated modules for DPI cycling and Actions Ring state management.
• Inter-process communication occurs via openlogi-ipc, while shared data structures live in openlogi-core.

Frequently Asked Questions

Why does openlogi-agent-core run separately from the GUI?

Separating the agent from the graphical interface prevents the heavyweight GPUI stack from interfering with time-sensitive input processing. This architecture ensures that input hooks remain active even when the GUI is closed, and allows the interface to be updated or restarted without disrupting device connectivity or dropping captured events.

What platforms does the input hook runtime support?

According to the source code in crates/openlogi-agent-core/src/, the runtime implements CGEventTap for macOS systems and evdev/uinput for Linux. These platform-specific backends enable raw input capture without requiring GUI dependencies on either operating system.

How does openlogi-agent-core communicate with the OpenLogi GUI?

The agent uses the IPC contract defined in the openlogi-ipc crate to exchange messages with the GUI process. This contract handles state synchronization for the Actions Ring, DPI settings, and configuration changes while maintaining strict separation between the headless agent and the visual interface.

Can openlogi-agent-core function without the GUI installed?

Yes, the crate is designed to operate independently as a headless service. Since it contains no GUI dependencies and handles all hardware communication directly through the orchestrator and watchers, the agent can run continuously in the background to manage input devices and execute button mappings without the graphical interface present.

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