Understanding the OpenLogi Overlay Process: Architecture and IPC Communication

The OpenLogi overlay process is a lightweight, cursor-centered UI binary that renders the Actions Ring and communicates with the core agent via IPC, operating independently from HID handling to provide per-application shortcut interfaces.

The OpenLogi overlay process serves as the visual interface layer in the AprilNEA/OpenLogi input customization ecosystem. Unlike monolithic applications that combine UI and hardware control, this Rust-based component maintains strict separation of concerns by functioning as a pure IPC client to the background agent.

What Is the OpenLogi Overlay Process?

The OpenLogi overlay is an independent binary (openlogi-overlay) that provides the Actions Ring—a set of eight shortcut icons appearing around the mouse pointer. This component focuses exclusively on visual feedback and user interaction, deliberately avoiding any direct hardware input handling.

The overlay operates as a sibling process to the GUI, not a child process. According to the architecture documented in AGENTS.md, it links against the shared UI crate openlogi-ui but never depends on the desktop crate, ensuring clean separation between visual presentation and core application logic.

IPC Architecture and Agent Communication

Rather than accessing HID devices directly, the OpenLogi overlay process communicates with the long-running agent via tarpc/bincode over a local socket. This design choice keeps the overlay entirely free of HID-specific code, making it a pure IPC client that subscribes to state updates from the agent.

Key architectural decisions include:

• No HID ownership: The overlay does not own the HID input hook—that responsibility belongs exclusively to the agent
• State synchronization: The overlay simply renders the ring based on updates received through the IPC contract
• Independent lifecycle: Because it communicates via IPC, the overlay can be launched, stopped, or replaced without affecting core HID handling

Core Responsibilities of the Overlay

The primary purpose of the OpenLogi overlay process is to display the Actions Ring and handle per-application overlay layouts. The ring reacts dynamically to the current application focus, allowing customization for specific software contexts.

When active, the overlay provides fast access to actions such as:

• DPI sensitivity changes
• Button remapping triggers
• Custom script execution

These capabilities are implemented through three critical source files in the crates/openlogi-overlay directory.

Key Implementation Files

Entry Point and Setup

The file crates/openlogi-overlay/src/main.rs serves as the entry point for the overlay binary. It initializes the IPC client connection and establishes the main UI rendering loop, setting up the communication channel with the agent process.

Actions Ring Rendering

Visual layout and rendering logic reside in crates/openlogi-overlay/src/ring.rs. This module implements the circular arrangement of eight shortcut icons and handles the cursor-centered positioning system that follows mouse movement.

IPC Session Management

The crates/openlogi-overlay/src/session.rs file manages the RingSession struct, which handles connection establishment with the agent and processes incoming state updates. This session layer abstracts the tarpc/bincode communication protocol into a cleaner API for the UI components.

Practical Code Examples

To start the overlay process from the command line, navigate to the repository root and execute:

# Starting the overlay from the command line

# (the binary lives in `crates/openlogi-overlay`)

$ cargo run -p openlogi-overlay

Programmatically connecting to the agent requires creating a RingSession that binds to the local IPC socket:

// Example of creating a ring session (simplified)
use openlogi_overlay::session::RingSession;

fn main() {
    // Connect to the agent over the local IPC socket
    let mut session = RingSession::connect().expect("cannot connect to agent");
    // Show the ring at the current cursor position
    session.show_ring();
}

External components can invoke overlay actions through the OverlayClient struct, which encapsulates the IPC messaging protocol:

// Sending a custom action to the overlay (via IPC)
use openlogi_ipc::client::OverlayClient;

fn trigger_custom_action() {
    let client = OverlayClient::new().unwrap();
    client.invoke_action("my_custom_action".into()).unwrap();
}

These patterns demonstrate how the overlay maintains its role as a pure visualization layer while relying entirely on the agent for state management and input processing.

Summary

• The OpenLogi overlay process is a standalone binary responsible solely for rendering the cursor-centered Actions Ring UI
• It operates as an IPC client to the agent using tarpc/bincode over local sockets, never handling HID input directly
• The overlay links against openlogi-ui but remains independent of the desktop crate, functioning as a sibling process to the main GUI
• Key implementation files include main.rs (entry point), ring.rs (visual rendering), and session.rs (IPC management)
• Per-application customization and shortcut access are enabled through state synchronization with the agent rather than direct hardware access

Frequently Asked Questions

How does the OpenLogi overlay process communicate with the agent?

The overlay process communicates via tarpc/bincode over a local socket, functioning as a pure IPC client. As documented in AGENTS.md, it subscribes to state updates from the agent rather than polling hardware directly, ensuring the overlay remains free of HID-specific code.

Why doesn't the overlay handle HID input directly?

The architecture deliberately separates concerns: the agent owns the HID input hook while the overlay focuses exclusively on visualization. This prevents UI crashes from affecting hardware input processing and allows the overlay to be restarted without interrupting mouse or keyboard functionality.

Can the overlay process run independently of the main GUI?

Yes. The overlay is a sibling process, not a child process, of the GUI. According to the AGENTS.md architecture specification, it can be launched, stopped, or replaced independently because it communicates with the agent through IPC rather than depending on the desktop crate or GUI process hierarchy.

Where is the Actions Ring rendering logic implemented?

The visual implementation resides in crates/openlogi-overlay/src/ring.rs, which handles the layout of eight shortcut icons around the cursor. The session management and agent communication occur in crates/openlogi-overlay/src/session.rs, while crates/openlogi-overlay/src/main.rs serves as the binary entry point.

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