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

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 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 and crate-specific AGENTS.md files (e.g., 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 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.

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 to ensure the workspace compiles:

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.

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:

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:

cargo test -p openlogi-agent-core

The CI configuration in .github/workflows/ci.yml defines which tests are mandatory for merge.

5. Documentation and Localization

Update relevant Markdown documentation (e.g., docs/USAGE.md, docs/CONFIGURATION.md) and localization files in crates/openlogi-ui/locales/*.yml. The i18n rules in .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 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.

Key Code Examples for OpenLogi Contributors

Building the Desktop Application

# 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:

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:

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

Updating Localization

Add keys consistently across all locale files:

# 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.

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 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
• 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 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 for the shared component library and .claude/rules/i18n.md for localization requirements.

What files should I read before submitting a pull request?

Read the root 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 (e.g., crates/openlogi-desktop/AGENTS.md for GUI-specific contracts). Also review CODE_OF_CONDUCT.md and docs/DEVELOPMENT.md for community standards and build instructions.

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