OpenLogi Overlay Binary: A Separate GPUI Process from the Main Desktop Application

Yes, the openlogi-overlay binary runs as an independent GPUI-based process that operates as a sibling to the main desktop application rather than running inside it.

The AprilNEA/OpenLogi repository implements a deliberate three-process architecture where the overlay component maintains its own process image separate from the main GUI. This design separates the Actions Ring cursor-centered interface from the primary desktop window, enabling independent lifecycle management and rendering contexts.

The Three-Process Architecture Model

OpenLogi ships with three distinct executables that communicate via tarpc-based IPC:

• openlogi-desktop: The primary GPUI desktop interface (main GUI)
• openlogi-agent: Background server handling device I/O and input hooks
• openlogi-overlay: The cursor-centered Actions Ring helper using its own GPUI context

According to the architecture documentation in AGENTS.md, these three processes "ship in one install — GUI, agent, overlay — and the overlay is a sibling of the GUI, not a part of it." This separation ensures that overlay rendering failures or crashes do not destabilize the main desktop application.

Evidence of Process Separation in the Source Code

Crate Dependencies

The openlogi-overlay crate explicitly avoids linking against the desktop crate. In crates/openlogi-overlay/Cargo.toml, the binary declares dependencies only on openlogi-ui and GPUI libraries, never on openlogi-desktop:

# crates/openlogi-overlay/Cargo.toml

[dependencies]
openlogi-ui = { path = "../openlogi-ui" }
gpui = { git = "https://github.com/zed-industries/zed" }

This dependency isolation confirms that the overlay builds as a standalone executable with its own main.rs entry point at crates/openlogi-overlay/src/main.rs.

Process Spawning Implementation

The openlogi-agent crate manages the overlay lifecycle, not the desktop application. In crates/openlogi-agent/src/overlay.rs, the agent spawns the overlay as a child process using standard library commands:

// crates/openlogi-agent/src/overlay.rs
let overlay_path = find_on_path("openlogi-overlay");
std::process::Command::new(overlay_path)
    .arg("--socket")
    .arg(&ipc_path)           // path to the tarpc socket
    .spawn()
    .expect("Failed to start openlogi-overlay");

This implementation detail confirms that openlogi-desktop never directly executes the overlay binary; instead, the agent launches it as a sibling process with its own process ID and memory space.

Inter-Process Communication Between Overlay and Desktop

Because the overlay runs separately from the main desktop application, state synchronization occurs through the openlogi-ipc crate. Both processes implement a shared tarpc service trait defined in crates/openlogi-ipc/src/lib.rs:

// crates/openlogi-ipc/src/lib.rs
#[tarpc::service]
pub trait Overlay {
    async fn update_ring(state: RingState) -> ();
}

The desktop pushes ring-state updates to the overlay process via this IPC channel, while the overlay renders its GPUI window independently. The default Unix socket path resides at $TMPDIR/openlogi.sock, though this is configurable via the --socket argument.

Running and Debugging the Overlay Process

You can execute the overlay binary independently for testing purposes. From the repository root after building:

# Manual execution for debugging

target/debug/openlogi-overlay

When launched manually, the overlay spawns a small cursor-centered window displaying the Actions Ring and attempts to connect to the agent via IPC. This standalone execution capability further confirms its status as a separate GPUI process with autonomous window management.

The UI crate's public documentation in crates/openlogi-ui/src/lib.rs explicitly describes the overlay as the "Actions Ring overlay helper," while docs/DEVELOPMENT.md notes that this component runs "alongside the GUI" as a distinct entity.

Summary

Key takeaways regarding the openlogi-overlay binary architecture:

• Independent process: The overlay runs as a separate OS process with its own GPUI context, not as a thread or window within openlogi-desktop
• Sibling relationship: It operates alongside the main GUI as a peer process, launched by the agent rather than the desktop
• Isolated dependencies: The overlay links only against openlogi-ui and GPUI libraries, avoiding direct coupling to the desktop crate
• IPC-based communication: State synchronization occurs through tarpc services over Unix sockets, not shared memory or function calls
• Standalone execution: The binary can run independently for debugging, rendering its own window without the desktop application present

Frequently Asked Questions

Is the openlogi-overlay embedded inside the main desktop window?

No. The overlay is not embedded inside the desktop window or process. According to the AGENTS.md architecture guide, it is explicitly a "sibling" process that renders its own separate GPUI window. The overlay crate at crates/openlogi-overlay/src/main.rs contains its own application entry point and event loop independent of openlogi-desktop.

How does the overlay communicate with the main application?

Communication happens through tarpc IPC via the openlogi-ipc crate. The desktop sends state updates using the Overlay service trait's update_ring method, transmitting data over a Unix domain socket. This inter-process approach allows the overlay to receive ring-state changes without sharing memory space with the desktop process.

Can I run the overlay binary independently for testing?

Yes. You can execute target/debug/openlogi-overlay directly from the command line. When run manually, it spawns the cursor-centered Actions Ring window and attempts to connect to the agent socket at $TMPDIR/openlogi.sock. This standalone execution mode is useful for debugging overlay-specific rendering issues without launching the full desktop application.

Why is the overlay a separate process instead of a thread?

The separation provides fault isolation and independent rendering contexts. Because GPUI manages its own windowing and event loops, running the overlay as a separate process prevents crashes in the Actions Ring from destabilizing the main desktop interface. This architecture also allows the agent to manage overlay lifecycle independently, restarting the helper without affecting the primary GUI session.

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