OpenLogi Crate Map Explained: Purpose, Structure, and Developer Workflow

The OpenLogi crate map is a high‑level architectural overview that lists every crate in the workspace, defines responsibilities, exposes dependency relationships, and guides contributors to the correct module for any change.

The OpenLogi project is a Rust workspace for managing Logitech HID++ devices with a modular, cross‑platform architecture. The OpenLogi crate map serves as the single source of truth for how this workspace is organized, making it indispensable for both new contributors and maintainers. This article breaks down the purpose of the crate map, its structure, and how to use it effectively when navigating the codebase.

What the OpenLogi Crate Map Achieves

The crate map documented in AGENTS.md fulfills six critical functions for the project:

Architectural Transparency

The map groups crates by functional area—CLI, core types, HID++, device layer, UI, agent, overlay, IPC—making the project's modular split immediately visible. Rather than hunting through crates/ directories, developers see at a glance how independent, well‑scoped modules compose the system.

Clear Ownership Boundaries

Every crate entry includes a concise tagline defining its scope. For example, openlogi-core is described as "Pure types: TOML config, device model, action catalog"—explicitly stating what it owns and, by omission, what it does not. This prevents responsibility creep across crate boundaries.

Dependency Visualization

Arrows and tables illustrate compile‑time relationships: openlogi-device depends on openlogi-hidpp, which in turn depends on the lower‑level hidpp crate; openlogi-desktop flows through openlogi-ui to gpui. These chains help developers anticipate the blast radius of changes.

Onboarding Acceleration

New contributors can locate entry points without deep code archaeology. UI work? Start at openlogi-ui. HID++ protocol changes? Head to openlogi-hidpp. The crate map reduces cognitive load and encourages safe, scoped refactoring.

Release Engineering Support

The xtask release tooling references the crate map to determine version bumps, documentation updates, and CI checks when changes touch specific modules. This automates consistency across the workspace.

Cross‑Platform Clarity

Platform‑specific crates—openlogi-hook, openlogi-inject, openlogi-hid—are explicitly flagged. Developers are reminded that #[cfg(target_os = …)] code lives in isolated crates and must respect the project's cross‑platform rules.

Complete OpenLogi Crate Reference

The following table lists all crates as documented in AGENTS.md, with their roles and source locations:

Crate	Role	Source Path
openlogi	CLI front‑end, thin wrapper over openlogi-cli	crates/openlogi
openlogi-cli	Command‑line dispatch, falls back to direct hardware enumeration	crates/openlogi-cli
openlogi-core	Pure data types: TOML config, device model, action catalog	crates/openlogi-core
openlogi-device	HID++ device layer (enumeration, probing, writes)	crates/openlogi-device
openlogi-hidpp	Hard‑fork of the hidpp protocol crate (protocol implementation)	crates/openlogi-hidpp
openlogi-hid	Host‑specific transport (async-hid, macOS Input Monitoring, probe cache)	crates/openlogi-hid
openlogi-agent	Runtime HID/input server (the "agent" process)	crates/openlogi-agent
openlogi-agent-core	Shared orchestration for DPI cycling, action‑ring sessions	crates/openlogi-agent-core
openlogi-hook	OS‑specific input capture (evdev, CGEventTap, WH_MOUSE_LL)	crates/openlogi-hook
openlogi-inject	OS‑specific input synthesis (SendInput, uinput, CGEvent)	crates/openlogi-inject
openlogi-ui	Shared UI assets, GPUI geometry and icons	crates/openlogi-ui
openlogi-desktop	Full GPUI desktop application (main GUI)	crates/openlogi-desktop
openlogi-overlay	Minimal IPC client for the Actions Ring cursor‑centred overlay	crates/openlogi-overlay
openlogi-ipc	tarpc/bincode IPC contract and transport implementation	crates/openlogi-ipc
openlogi-camera	Logitech UVC enumeration, capture, camera‑permission APIs	crates/openlogi-camera
openlogi-assets	Device‑render registry and cached asset fetching	crates/openlogi-assets
openlogi-permissions	Privacy‑permission status handling (macOS TCC, Linux device files)	crates/openlogi-permissions

Practical Workflow: Using the Crate Map for Changes

The crate map transforms abstract architecture into actionable navigation. Consider adding a new DPI step to a Logitech mouse:

1. Identify the device layer: The openlogi-device crate owns all device writes—start at crates/openlogi-device/src/lib.rs.

2. Trace to protocol implementation: Follow the dependency to openlogi-hidpp for low‑level command encoding at crates/openlogi-hidpp/src/lib.rs.

3. Surface in UI if needed: Edit openlogi-ui for shared components, then openlogi-desktop at crates/openlogi-desktop/src/lib.rs to expose the new setting in the main GUI.

Without the crate map, this chain would require reverse‑engineering Cargo.toml files and guessing at responsibility boundaries. The map makes these steps explicit, preventing accidental edits in unrelated crates.

Key Files for Deep Dives

File	Purpose
AGENTS.md (crate map section)	Authoritative listing of crates, responsibilities, and dependencies
crates/openlogi-core/src/lib.rs	Pure data structures used across the workspace
crates/openlogi-device/src/lib.rs	Central hub for device operations and HID++ writes
crates/openlogi-ipc/src/lib.rs	IPC contract for desktop, overlay, and agent processes
crates/openlogi-desktop/src/lib.rs	Main GUI logic consuming UI crate and agent IPC
crates/openlogi-overlay/src/lib.rs	Minimal client demonstrating overlay‑to‑agent IPC usage

Summary

• The OpenLogi crate map in AGENTS.md is the backbone of the project's modular design.

• It provides architectural transparency, clear ownership, dependency visualization, onboarding guidance, release automation, and cross‑platform awareness.

• All 17 crates are grouped by function with explicit roles, from openlogi-core (pure types) to openlogi-desktop (full GUI) and openlogi-overlay (minimal IPC client).

• Contributors should consult the crate map before any change to identify the correct entry point and understand dependency chains.

Frequently Asked Questions

Where is the OpenLogi crate map documented?

The crate map is documented in the AGENTS.md file at the repository root, specifically in its dedicated crate map section. This file serves as the authoritative reference for all crate responsibilities and inter‑dependencies in the OpenLogi workspace.

How do I know which crate to modify for a feature?

Consult the crate map's role descriptions. UI changes flow through openlogi-ui and openlogi-desktop; device protocol work belongs in openlogi-device and openlogi-hidpp; platform‑specific input handling targets openlogi-hook or openlogi-inject. The map's dependency arrows then confirm which downstream crates may need updates.

What is the difference between openlogi-agent and openlogi-agent-core?

openlogi-agent is the runtime HID/input server process, while openlogi-agent-core provides shared orchestration logic used by that agent—such as DPI cycling and action‑ring session management. The core crate enables code reuse without pulling in the full agent runtime.

Why are platform‑specific crates like openlogi-hook isolated?

Isolation enforces cross‑platform discipline. By containing #[cfg(target_os = …)] code in dedicated crates, the crate map ensures developers cannot accidentally introduce platform‑specific logic into shared modules. This makes porting easier and compile‑time failures occur in predictable locations.

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