# How to Contribute to the OpenLogi Project: A Complete Guide to the Rust Codebase

> Learn how to contribute to the OpenLogi project by forking the repository, setting up Rust 1.98, and following the commit workflow. Start contributing to OpenLogi today!

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

---

**Contributing to OpenLogi requires forking the repository, setting up Rust 1.98+, and following the conventional commit workflow while respecting the Cargo workspace boundaries defined in the project's [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md) files.**

OpenLogi is a native, local-first alternative to Logitech Options+ written in Rust. If you want to contribute to the OpenLogi project, you will work within a multi-crate Cargo workspace that separates device logic, UI components, and background agents. This guide walks you through the repository structure, development environment setup, and the exact contribution workflow maintained by the project authors.

## Understanding the OpenLogi Workspace Architecture

OpenLogi organizes its codebase as a Cargo workspace divided into ten distinct crates. Each crate enforces strict boundaries—for example, **`openlogi-core`** contains pure types and TOML configuration with no I/O, while **`openlogi-device`** handles all HID++ device enumeration, probing, and session management.

The workspace layout follows this responsibility matrix:

- **`openlogi-agent-core`** – Shared orchestration logic for hook runtimes, DPI cycles, and action-ring state
- **`openlogi-agent`** – Background server that owns input hooks and all device I/O
- **`openlogi-desktop`** – GPUI-based desktop GUI (the main user-facing application)
- **`openlogi-overlay`** – Cursor-centered actions-ring client (sibling to the GUI)
- **`openlogi-ui`** – Shared UI assets, localization, and GPUI components used by both desktop and overlay
- **`openlogi-hidpp`** – Vendored fork of the `hidpp` protocol crate
- **`openlogi-assets`** – Asset registry and cached fetching from OpenLogi mirrors
- **`xtask`** – Build-time helper utilities for packaging and release automation

Architectural contracts for each crate are documented in root **[`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md)** and crate-specific [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md) files (e.g., [`crates/openlogi-desktop/AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/AGENTS.md) for GUI contracts). Consult these files before modifying cross-crate interfaces.

## Setting Up Your Development Environment

### Prerequisites and Toolchain

OpenLogi targets Rust 1.98 (current stable MSRV) and manages this via a [`rust-toolchain.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/rust-toolchain.toml) file that `rustup` automatically detects.

1. **Fork and clone** the repository on GitHub, then clone your fork locally.

2. **Install the Rust toolchain**—the repository will automatically select the correct version via [`rust-toolchain.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/rust-toolchain.toml).

3. **Optional: Enable `devenv`**—OpenLogi supports a Nix-based development environment. If you have `direnv` installed, run `direnv allow` in the repository root to pull in correct dependencies.

### Verify Your Setup

Run the inner-loop checks defined in [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md) to ensure the workspace compiles:

```bash
cargo check            # Type-checking only

cargo test             # Run the full test suite

```

## The OpenLogi Contribution Workflow

### 1. Planning and Branching

Before writing code, open an issue using the templates in `.github/ISSUE_TEMPLATE/` to discuss scope for bug fixes or sizable features. Create a descriptive, kebab-cased branch name such as `feat/dpi-cycle` or `fix/overlay-crash`, as specified in the **Git** section of [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md).

### 2. Coding Within Crate Boundaries

Implement changes in the appropriate crate only. Respect the architectural contract:

- UI changes belong in **`openlogi-ui`**, not `openlogi-agent`
- Device logic stays within **`openlogi-device`**
- Pure data types and configuration live in **`openlogi-core`**

### 3. Linting and Formatting

Run the project's strict Rust standards codified in [`.claude/rules/rust.md`](https://github.com/AprilNEA/OpenLogi/blob/main/.claude/rules/rust.md):

```bash
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings

```

### 4. Testing

Add unit and integration tests for new functionality. Run crate-specific tests to avoid unnecessary build times:

```bash
cargo test -p openlogi-agent-core

```

The CI configuration in [`.github/workflows/ci.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/workflows/ci.yml) defines which tests are mandatory for merge.

### 5. Documentation and Localization

Update relevant Markdown documentation (e.g., [`docs/USAGE.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/USAGE.md), [`docs/CONFIGURATION.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/CONFIGURATION.md)) and localization files in `crates/openlogi-ui/locales/*.yml`. The i18n rules in [`.claude/rules/i18n.md`](https://github.com/AprilNEA/OpenLogi/blob/main/.claude/rules/i18n.md) require key parity across all language bundles.

### 6. Submitting Your Pull Request

Push your branch and open a PR using **conventional commit** format: `type(scope): description` (e.g., `feat(dpi): add custom preset handling`).

The CI pipeline defined in [`.github/workflows/ci.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/workflows/ci.yml) automatically runs full workspace checks. Ensure all jobs pass. Reviewers will preserve your authorship via `Co-authored-by` tags for contributor-originated commits, as documented in [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md).

## Key Code Examples for OpenLogi Contributors

### Building the Desktop Application

```bash

# From the repository root

cargo build -p openlogi-desktop         # Builds the GUI

cargo run -p openlogi-desktop           # Launches the desktop app

```

### Running the Mock Agent

Develop without physical Logitech hardware using the mock agent:

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

```

### Adding a New Action to the Catalog

Modify the Action enum in [`crates/openlogi-core/src/action.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/action.rs):

```rust
// crates/openlogi-core/src/action.rs
pub enum Action {
    // Existing variants...
    CustomCommand(String), // ← new variant
}

```

### Updating Localization

Add keys consistently across all locale files:

```yaml

# crates/openlogi-ui/locales/en.yml

reset_button: "Reset"

```

## Best Practices for Contributing to OpenLogi

**Keep commits atomic.** Each commit should address a single logical change with a clear message following the `type(scope): description` convention.

**Run tiered checks.** Before pushing, execute `cargo clippy -p <crate>` on affected packages to catch errors early and avoid CI failures.

**Respect platform gating.** Many modules contain `#[cfg(target_os = "...")]` blocks. When modifying platform-specific code in `crates/openlogi-device/src/inventory/`, verify compilation across macOS, Linux, and Windows per [`.claude/rules/cross-platform.md`](https://github.com/AprilNEA/OpenLogi/blob/main/.claude/rules/cross-platform.md).

**Maintain localization parity.** Always update all language bundles when adding UI strings to prevent i18n test failures.

## Summary

- OpenLogi uses a Cargo workspace with ten crates; consult [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md) files before crossing crate boundaries
- Development requires Rust 1.98+ and optionally `devenv` for Nix-based environments
- Contributions must pass `cargo fmt`, `cargo clippy -D warnings`, and the CI pipeline in [`.github/workflows/ci.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/workflows/ci.yml)
- Use conventional commit format (`feat(scope): description`) and kebab-cased branch names
- Update localization files in `crates/openlogi-ui/locales/` and documentation in `docs/` alongside code changes

## Frequently Asked Questions

### What is the minimum Rust version required to contribute to OpenLogi?

OpenLogi requires Rust 1.98 (current stable) as its MSRV (Minimum Supported Rust Version). The repository includes a [`rust-toolchain.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/rust-toolchain.toml) file that automatically instructs `rustup` to install and use this version when you run any cargo commands in the project directory.

### How do I test my changes without owning Logitech hardware?

You can use the mock agent binary to simulate device interactions. Run `cargo run -p openlogi-agent --bin openlogi-agent-mock` to launch a simulated agent environment that allows development and testing of the desktop UI and overlay without physical HID++ devices connected.

### Where should I place UI code when contributing to OpenLogi?

All shared UI components, assets, and localization belong in the **`openlogi-ui`** crate, not in `openlogi-desktop` or `openlogi-agent`. The desktop application (`openlogi-desktop`) and overlay (`openlogi-overlay`) both depend on this crate. Consult [`crates/openlogi-ui/src/lib.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ui/src/lib.rs) for the shared component library and [`.claude/rules/i18n.md`](https://github.com/AprilNEA/OpenLogi/blob/main/.claude/rules/i18n.md) for localization requirements.

### What files should I read before submitting a pull request?

Read the root **[`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md)** for project-wide conventions regarding branching, commit style, and CI expectations. If you are modifying a specific crate, read its local [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md) (e.g., [`crates/openlogi-desktop/AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/AGENTS.md) for GUI-specific contracts). Also review **[`CODE_OF_CONDUCT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/CODE_OF_CONDUCT.md)** and **[`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md)** for community standards and build instructions.