OpenLogi Developer Documentation: Complete Guide to Building and Contributing

OpenLogi maintains comprehensive developer documentation in the docs/ directory and .claude/rules/ subdirectory, covering everything from Rust toolchain setup and multi-crate workspace architecture to IPC protocols and cross-platform coding standards.

The AprilNEA/OpenLogi repository is a Rust-based application for managing Logitech input devices through a multi-process architecture. For OpenLogi developers navigating this codebase, the project provides extensive documentation guides that explain the build system, configuration schemas, and contribution workflows without requiring external wiki pages.

Core Developer Guides in the docs/ Directory

The primary developer documentation lives in the repository root under docs/, with each file targeting specific phases of the development lifecycle.

Development Environment Setup

The docs/DEVELOPMENT.md file contains the authoritative guide for preparing your build environment. It details how to install the Rust toolchain, configure devenv for reproducible development shells, and use cargo xtask for automation tasks. The document explains the multi-crate workspace structure declared in the root Cargo.toml, ensuring developers understand how the openlogi-core, openlogi-agent, and openlogi-desktop crates interact.

CLI Usage and Integration

For developers extending the command-line interface, docs/USAGE.md documents the openlogi-cli binary. It covers how to invoke device enumeration, manage DPI profiles, and interact with the background agent process. This guide is essential when modifying crates/openlogi-cli/src/main.rs or adding new subcommands to the CLI parser.

Configuration Schema Reference

The docs/CONFIGURATION.md file defines the TOML schema for config.toml, including per-device profile definitions, SmartShift settings, and action mapping syntax. Developers working on the configuration parser in crates/openlogi-core/src/lib.rs should reference this document to maintain backward compatibility when adding new configuration fields.

Architecture and IPC Specifications

Understanding the high-level system design requires consulting architecture-specific documentation that explains how the GUI, agent, and overlay processes communicate.

System Architecture Overview

The AGENTS.md file at the repository root provides a high-level crate diagram and explains the role of each subsystem. It maps the relationship between the desktop GUI entry point at crates/openlogi-desktop/src/main.rs and the background agent entry point at crates/openlogi-agent/src/main.rs. This document clarifies the separation of concerns between device I/O handling and the user interface layer.

IPC Protocol Details

For developers working on inter-process communication, .claude/rules/ipc-protocol.md specifies the Tarpc-based message protocol exchanged between components. The actual contract implementation resides in crates/openlogi-ipc/src/ipc.rs, where message serialization and service definitions are maintained. This documentation is critical when adding new RPC methods or modifying the communication flow between the agent and desktop UI.

Coding Standards and Contribution Guidelines

OpenLogi enforces strict coding standards through documented rules that ensure consistency across the Rust codebase.

Rust Coding Standards

The .claude/rules/rust.md file establishes project-wide lint configurations, formatting rules enforced by rustfmt, and conventional commit message guidelines. It specifies how to structure error handling and async code patterns used throughout the workspace. Developers should review this before submitting pull requests to ensure compliance with the project's quality gates.

Cross-Platform Development Rules

Since OpenLogi targets Linux, macOS, and Windows, .claude/rules/cross-platform.md provides guidelines for writing platform-specific code using conditional compilation attributes like #[cfg(target_os = "...")]. This document explains how to handle platform differences in device detection and input hook implementations without breaking other target builds.

Internationalization Standards

The .claude/rules/i18n.md guide explains how localization files are organized within the repository and documents the process for adding new language strings. This is essential for developers modifying UI components in the desktop crate who need to maintain translatable user interfaces.

Contributing Workflow

The CONTRIBUTING.md file in the repository root outlines the pull request process, while docs/SECURITY.md details the threat model and data-privacy guarantees. Together, these documents provide the complete workflow for external contributors, from local development to security review requirements.

CI, Testing, and Build Automation

Understanding the automated testing infrastructure helps developers verify changes locally before pushing to CI.

Continuous Integration Reference

The .claude/rules/ci.md file maps GitHub Actions workflow jobs to specific local commands. It explains how the CI organizes build, test, and packaging stages, allowing developers to reproduce exact CI conditions using the cargo xtask automation defined in xtask/src/main.rs.

Testing Workflows

To run the complete test suite for specific crates during development, use the following patterns derived from the CI configuration:

# Run tests for the agent core only

cargo test -p openlogi-agent-core

# Run the desktop UI locally with hot-reload

direnv exec . cargo run -p openlogi-desktop

Practical Developer Workflows

The following examples illustrate typical tasks documented across the OpenLogi developer guides.

Building the Desktop Application

To build and run the desktop GUI locally using the development environment setup described in docs/DEVELOPMENT.md:

direnv exec . cargo run -p openlogi-desktop

Working with the CLI

When extending the CLI functionality documented in docs/USAGE.md, reference this pattern from the source:

// Example: CLI dispatch for device listing
use openlogi_cli::Cli;
use clap::Parser;

fn main() {
    let args = Cli::parse();
    args.run(); // Dispatches to list, assets, diag, etc.
}

Modifying Configuration Profiles

When testing configuration changes against the schema defined in docs/CONFIGURATION.md, use this TOML structure:

# Example: Custom device profile in config.toml

[[profile]]
name = "Gaming"
device = "Logitech G502"
dpi = 8000
actions = { button1 = "macro", button2 = "sensitivity_up" }

Summary

• Primary documentation for OpenLogi developers resides in the docs/ directory, with docs/DEVELOPMENT.md serving as the main onboarding guide.
• Architecture documentation in AGENTS.md and .claude/rules/ipc-protocol.md explains the multi-process design and IPC contracts implemented in crates/openlogi-ipc/src/ipc.rs.
• Coding standards are enforced through .claude/rules/rust.md and .claude/rules/cross-platform.md, which govern how code is written for the multi-crate workspace defined in the root Cargo.toml.
• Build and test automation is configured via xtask/src/main.rs and documented in .claude/rules/ci.md, enabling local reproduction of GitHub Actions workflows.

Frequently Asked Questions

Where is the main developer setup guide for OpenLogi?

The primary setup guide is located at docs/DEVELOPMENT.md in the repository root. This document explains how to install the Rust toolchain, configure the devenv environment, and build the multi-crate workspace using cargo xtask commands.

How do I understand the IPC communication between the GUI and agent processes?

Consult .claude/rules/ipc-protocol.md for the Tarpc-based message specification, then examine crates/openlogi-ipc/src/ipc.rs for the actual implementation. The AGENTS.md file provides the high-level architecture context for how these IPC messages flow between crates/openlogi-desktop/src/main.rs and crates/openlogi-agent/src/main.rs.

What coding standards must I follow when contributing Rust code to OpenLogi?

All contributions must comply with .claude/rules/rust.md, which specifies lint rules, formatting requirements, and conventional commit guidelines. For platform-specific code, also review .claude/rules/cross-platform.md to ensure proper use of conditional compilation attributes.

How do I run tests for specific crates in the OpenLogi workspace?

Use the -p flag with Cargo to target specific crates. For example, run cargo test -p openlogi-agent-core to test only the agent core logic, or cargo test -p openlogi-core to validate configuration parsing. The .claude/rules/ci.md document maps these commands to their CI equivalents for local verification.

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