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

> Develop for OpenLogi by cloning the Rust workspace, installing the toolchain, and launching the GPUI GUI. Test hardware-free with the mock agent. Start building your Logitech alternative today.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: how-to-guide
- Published: 2026-09-10

---

**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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/main.rs) |
| **Overlay** | Cursor‑centred actions‑ring for quick device control. | [`crates/openlogi-overlay/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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:
  

```bash
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:

```bash
devenv tasks run openlogi:ci

```

## Building and Running OpenLogi Locally

### Basic Build Commands

Clone the repository and run a sanity check:

```bash
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:

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

```

Then launch the GUI against it in another:

```bash
OPENLOGI_DEV_AGENT=0 cargo run -p openlogi-desktop

```

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

```bash
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:

```bash
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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/.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`](https://github.com/AprilNEA/OpenLogi/blob/main/.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:

```bash
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:

```bash
cargo run -p xtask -- linux package

```

Configure package contents in [`packaging/linux/nfpm.yaml`](https://github.com/AprilNEA/OpenLogi/blob/main/packaging/linux/nfpm.yaml).

### Nix Package

For NixOS users:

```bash
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:

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

```

### Running CI Locally

Execute the full CI matrix locally:

```bash
cargo xtask ci

```

Or via devenv:

```bash
devenv tasks run openlogi:ci

```

## Internationalization (i18n)

All GUI strings live in `crates/openlogi-ui/locales/*.toml` with [`en.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/en.toml) as the source of truth. Parity tests ensure every locale contains the same keys. Manage translations via:

```bash
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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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.