How to Run the OpenLogi Desktop GUI in Development Mode

Launch the OpenLogi desktop GUI in development mode by running cargo run -p openlogi-desktop from the workspace root, or use cargo run -p xtask -- macos dev-bundle on macOS to generate a proper .app bundle with the correct icon and menu-bar name.

The OpenLogi project provides a Rust-based desktop GUI for managing Logitech devices. Whether you are contributing to the codebase or testing features locally, this guide covers the exact commands and configuration files needed to run the openlogi-desktop binary in development mode according to the AprilNEA/OpenLogi source code.

Quick Start with Cargo

The simplest way to run the GUI uses Cargo's workspace-aware package selection. The binary entry point resides in crates/openlogi-desktop/src/main.rs.

Basic Launch

Execute the following from the repository root to build and run the GUI in debug mode:

cargo run -p openlogi-desktop

This compiles the raw binary (not a macOS .app bundle), which is sufficient for rapid iteration across Linux and macOS.

macOS Development Bundle

For macOS developers who need the proper app icon and menu-bar label OpenLogi Dev, the workspace provides an xtask runner defined in .cargo/config.toml:

cargo run -p xtask -- macos dev-bundle
open target/dev/OpenLogi.app

The first command invokes the bundling logic implemented in xtask/src/main.rs, which assembles target/dev/OpenLogi.app as documented in docs/DEVELOPMENT.md (lines 81-90). The second command launches the bundled application with full macOS integration.

Hardware-Free Development with Mock Agent

You can develop and test the GUI without physical Logitech hardware by using the mock IPC server implemented in crates/openlogi-agent/src/bin/openlogi-agent-mock.rs.

Starting the Mock IPC Server

Start the mock agent in the background before launching the GUI:

cargo run -p openlogi-agent --bin openlogi-agent-mock &

Connecting the GUI to the Mock Agent

Prevent the GUI from auto-spawning its own agent by setting OPENLOGI_DEV_AGENT=0, then launch the desktop client:

OPENLOGI_DEV_AGENT=0 cargo run -p openlogi-desktop

This configuration binds the GUI to the mock server, satisfying the IPC contract without requiring USB hardware. These commands are documented in docs/DEVELOPMENT.md (lines 23-31).

Optional Nix-Based Development Environment

If you use the optional devenv Nix shell, the repository exposes preconfigured tasks that mirror the Cargo workflows. Run the GUI with:

devenv tasks run openlogi:gui

For comprehensive checks including formatting, Clippy, tests, and documentation, execute:

devenv tasks run openlogi:check

These tasks are documented in docs/DEVELOPMENT.md (lines 44-51), which serves as the primary reference for the project's development workflow.

Summary

• Use cargo run -p openlogi-desktop for the fastest cross-platform launch during development.
• Generate macOS bundles with cargo run -p xtask -- macos dev-bundle to test native app behavior including icons and menu-bar names.
• Test without hardware by running openlogi-agent-mock and setting OPENLOGI_DEV_AGENT=0 before launching the GUI.
• Reference docs/DEVELOPMENT.md for authoritative command documentation and additional context on lines 23-31 (mock agent) and 81-90 (macOS bundling).

Frequently Asked Questions

What is the entry point for the OpenLogi desktop GUI?

The binary entry point is crates/openlogi-desktop/src/main.rs. This file initializes the application and is executed when you run cargo run -p openlogi-desktop.

How do I get the proper macOS app icon and menu bar name?

Run cargo run -p xtask -- macos dev-bundle to create target/dev/OpenLogi.app, then launch it with open target/dev/OpenLogi.app. This bundle displays the correct icon and shows OpenLogi Dev in the menu bar, unlike the raw binary.

Can I test the GUI without Logitech hardware connected?

Yes. Start the mock IPC server with cargo run -p openlogi-agent --bin openlogi-agent-mock, then launch the GUI with OPENLOGI_DEV_AGENT=0 cargo run -p openlogi-desktop. This setup is documented in docs/DEVELOPMENT.md (lines 23-31) and uses the mock agent implementation in crates/openlogi-agent/src/bin/openlogi-agent-mock.rs.

Where are the development commands documented?

All development workflows, including Cargo commands and devenv tasks, are documented in docs/DEVELOPMENT.md at the repository root (specifically lines 44-51 for general tasks and lines 81-90 for macOS bundling).

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