# OpenLogi Developer Documentation: Complete Guide to Building and Contributing

> Explore the OpenLogi developer documentation. This guide details Rust toolchain setup, workspace architecture, IPC protocols, and coding standards for contributing to the OpenLogi project.

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

---

**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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-cli/src/main.rs) or adding new subcommands to the CLI parser.

### Configuration Schema Reference

The [`docs/CONFIGURATION.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/CONFIGURATION.md) file defines the TOML schema for [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/main.rs) and the background agent entry point at [`crates/openlogi-agent/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/.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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/.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`](https://github.com/AprilNEA/OpenLogi/blob/main/.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`](https://github.com/AprilNEA/OpenLogi/blob/main/.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`](https://github.com/AprilNEA/OpenLogi/blob/main/CONTRIBUTING.md) file in the repository root outlines the pull request process, while [`docs/SECURITY.md`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/.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`](https://github.com/AprilNEA/OpenLogi/blob/main/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:

```bash

# 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`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md):

```bash
direnv exec . cargo run -p openlogi-desktop

```

### Working with the CLI

When extending the CLI functionality documented in [`docs/USAGE.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/USAGE.md), reference this pattern from the source:

```rust
// 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`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/CONFIGURATION.md), use this TOML structure:

```toml

# 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`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md) serving as the main onboarding guide.
- **Architecture documentation** in [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md) and [`.claude/rules/ipc-protocol.md`](https://github.com/AprilNEA/OpenLogi/blob/main/.claude/rules/ipc-protocol.md) explains the multi-process design and IPC contracts implemented in [`crates/openlogi-ipc/src/ipc.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/src/ipc.rs).
- **Coding standards** are enforced through [`.claude/rules/rust.md`](https://github.com/AprilNEA/OpenLogi/blob/main/.claude/rules/rust.md) and [`.claude/rules/cross-platform.md`](https://github.com/AprilNEA/OpenLogi/blob/main/.claude/rules/cross-platform.md), which govern how code is written for the multi-crate workspace defined in the root [`Cargo.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/Cargo.toml).
- **Build and test automation** is configured via [`xtask/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/main.rs) and documented in [`.claude/rules/ci.md`](https://github.com/AprilNEA/OpenLogi/blob/main/.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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/.claude/rules/ipc-protocol.md) for the Tarpc-based message specification, then examine [`crates/openlogi-ipc/src/ipc.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/src/ipc.rs) for the actual implementation. The [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md) file provides the high-level architecture context for how these IPC messages flow between [`crates/openlogi-desktop/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/main.rs) and [`crates/openlogi-agent/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/.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`](https://github.com/AprilNEA/OpenLogi/blob/main/.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`](https://github.com/AprilNEA/OpenLogi/blob/main/.claude/rules/ci.md) document maps these commands to their CI equivalents for local verification.