How to Develop for OpenLogi: A Complete Guide to Building the Local-First Logitech Alternative

To develop for OpenLogi, clone the Rust workspace, install the pinned toolchain (Rust 1.98+), and run cargo run -p openlogi-desktop to launch the GPUI-based GUI, using the mock agent for hardware-free testing.

OpenLogi is a native, local‑first alternative to Logitech Options+ built in Rust. The project uses a workspace architecture of small, single-responsibility crates that communicate via a versioned IPC protocol. This guide covers the complete development workflow from environment setup to packaging releases for macOS and Linux.

Understanding the OpenLogi Architecture

OpenLogi splits functionality across three distinct processes that communicate over a versioned, append‑only tarpc/bincode protocol defined in crates/openlogi-ipc/src/ipc.rs.

The Three-Process Runtime

Process	Responsibility	Entry Point
GUI	GPUI-based desktop client that renders the UI and talks to the agent via IPC.	crates/openlogi-desktop/src/lib.rs
Agent	Background service that owns HID++ I/O, the input hook, and per‑device state.	crates/openlogi-agent/src/main.rs
Overlay	Cursor‑centred actions‑ring for quick device control.	crates/openlogi-overlay/src/main.rs

Workspace Crate Responsibilities

The workspace contains over a dozen specialized crates. Key components include:

• openlogi-core – Pure types, TOML config, and button/action catalog with no I/O dependencies.
• openlogi-device – HID++ device layer for enumeration, probing, writes, and sessions.
• openlogi-hid – Host‑specific async‑HID transport with macOS input monitoring.
• openlogi-hook – OS input capture using macOS CGEventTap, Linux evdev + uinput, or Windows WH_MOUSE_LL.
• openlogi-inject – OS input synthesis for automation.
• openlogi-agent-core – Shared orchestration handling DPI cycles, SmartShift, lighting, and action‑ring state.
• xtask – Workspace helper for building, packaging, and CI tasks.

Development Environment Setup

Prerequisites

The toolchain is pinned in rust-toolchain.toml:

• Rust: Stable edition 2024 with MSRV 1.98
• macOS: Xcode 26+ with the Metal Toolchain component (required for GPUI shaders)
• Linux: Install system libraries:

sudo apt install libudev-dev gcc g++ clang libfontconfig-dev \
    libwayland-dev libxkbcommon-x11-dev libx11-xcb-dev \
    libssl-dev libzstd-dev pkg-config

Optional Nix Setup

For reproducible environments, use the provided devenv.nix which provisions the Rust toolchain, sccache, create-dmg, and all platform libraries:

devenv tasks run openlogi:ci

Building and Running OpenLogi Locally

Basic Build Commands

Clone the repository and run a sanity check:

git clone https://github.com/AprilNEA/OpenLogi
cd OpenLogi

# Build and run the CLI to list devices

cargo run -p openlogi --release -- list

# Launch the desktop GUI (requires running agent)

cargo run -p openlogi-desktop --release

Using the Mock Agent for Hardware-Free Development

When you lack Logitech hardware, the mock agent provides a scripted inventory that satisfies the IPC contract. Start the mock in one terminal:

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

Then launch the GUI against it in another:

OPENLOGI_DEV_AGENT=0 cargo run -p openlogi-desktop

The mock uses the dev profile by default. To test production socket connections:

OPENLOGI_PROFILE=prod cargo run -p openlogi-agent --bin openlogi-agent-mock
OPENLOGI_DEV_AGENT=0 OPENLOGI_PROFILE=prod cargo run -p openlogi-desktop

Running the Component Gallery

For rapid UI iteration without IPC or hardware, enable the component gallery:

OPENLOGI_COMPONENT_GALLERY=1 cargo run -p openlogi-desktop

This opens an isolated window showing every shared UI component in light/dark themes and all UI scales.

Development Workflows

Changing the IPC Protocol

When modifying the tarpc contract in crates/openlogi-ipc/src/ipc.rs:

1. Bump PROTOCOL_VERSION in the source file
2. Add a compatibility test in crates/openlogi-ipc/tests/wire_format.rs
3. Ensure the binary format remains append‑only to maintain backward compatibility

Adding New Crates

Follow the workspace conventions documented in .claude/rules/rust.md. Place pure logic in openlogi-core, hardware abstraction in openlogi-device, and platform‑specific code behind #[cfg(target_os = "...")] guards per .claude/rules/cross-platform.md.

Cross-Platform Input Handling

Platform‑specific implementations reside in:

• openlogi-hook – Input capture (CGEventTap, evdev, Windows hooks)
• openlogi-inject – Input synthesis (CGEvent, uinput/MPRIS, SendInput)

Run cross-platform linting before submitting changes to ensure conditional compilation covers all supported targets.

Packaging and Distribution

macOS DMG

Build a signed macOS package:

OPENLOGI_BUNDLE_ASSETS=1 OPENLOGI_SIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)" \
    cargo run -p xtask -- macos package

This produces target/release/OpenLogi.dmg.

Linux Packages

Generate .deb, .rpm, or .pkg.tar.zst via nfpm:

cargo run -p xtask -- linux package

Configure package contents in packaging/linux/nfpm.yaml.

Nix Package

For NixOS users:

nix build .#openlogi

This builds a reproducible package and the NixOS module.

Continuous Integration and Testing

Pre-Push Gate

Before pushing changes, ensure the pre‑push gate passes:

cargo fmt
cargo clippy
cargo test
cargo doc  # with warnings denied

Running CI Locally

Execute the full CI matrix locally:

cargo xtask ci

Or via devenv:

devenv tasks run openlogi:ci

Internationalization (i18n)

All GUI strings live in crates/openlogi-ui/locales/*.toml with en.toml as the source of truth. Parity tests ensure every locale contains the same keys. Manage translations via:

devenv tasks run openlogi:i18n-upload  # Upload to Crowdin

devenv tasks run openlogi:i18n-download  # Download translations

Summary

• OpenLogi development requires Rust 1.98+, platform‑specific system libraries, and optionally Nix/devenv for reproducible builds.
• The architecture separates concerns into three processes (GUI, Agent, Overlay) communicating via tarpc/bincode in crates/openlogi-ipc/src/ipc.rs.
• Use the mock agent (openlogi-agent-mock) to develop the UI without Logitech hardware by setting OPENLOGI_DEV_AGENT=0.
• Enable the component gallery with OPENLOGI_COMPONENT_GALLERY=1 for isolated UI iteration.
• IPC protocol changes require bumping PROTOCOL_VERSION and adding wire format tests.
• Package releases using cargo run -p xtask -- macos package or linux package, with optional code signing via OPENLOGI_SIGN_IDENTITY.

Frequently Asked Questions

Do I need Logitech hardware to develop for OpenLogi?

No. You can run the mock agent (cargo run -p openlogi-agent --bin openlogi-agent-mock) which provides a scripted device inventory that satisfies the IPC contract. Launch the GUI with OPENLOGI_DEV_AGENT=0 to connect to the mock instead of the real agent, enabling full UI development without physical devices.

How do I modify the communication protocol between the GUI and Agent?

Edit the tarpc service definitions in crates/openlogi-ipc/src/ipc.rs, then increment PROTOCOL_VERSION to signal breaking changes. You must add a test in crates/openlogi-ipc/tests/wire_format.rs to verify backward compatibility, as the protocol uses an append‑only binary format to maintain compatibility across versions.

What is the fastest way to test UI changes without running the full stack?

Enable the component gallery by setting OPENLOGI_COMPONENT_GALLERY=1 when running the desktop package. This opens an isolated window displaying every shared UI component in both light and dark themes, allowing rapid iteration without starting the agent or establishing IPC connections.

How do I package OpenLogi for distribution on macOS?

Run cargo run -p xtask -- macos package after setting OPENLOGI_BUNDLE_ASSETS=1. For code signing, export OPENLOGI_SIGN_IDENTITY with your Developer ID. The command produces target/release/OpenLogi.dmg ready for distribution.

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