Architecture

An overview of OpenLogi's components: GUI, agent, CLI, the HID++ crates, and the asset host.

OpenLogi runs as a background agent plus an on-demand GUI. The agent owns every device channel and the OS input hook; the GUI is a pure IPC client that starts the agent when it isn't already running, and the CLI talks to hardware directly for inventory and diagnostics.

Components

OpenLogi agent (openlogi-agent) — the background process: HID++ device I/O, the input hook, capture sessions, per-app watching, the menu-bar / tray item, pairing, and the Actions Ring overlay helper.
OpenLogi GUI (openlogi-gui) — a GPUI desktop app: device carousel, mouse diagram, keyboard model, action picker, and the settings windows. It holds no device state of its own.
OpenLogi CLI (openlogi) — headless inventory, asset sync, light and camera control, and on-device HID++ diagnostics.
assets.openlogi.org — a static host serving per-device renders and clickable-hotspot metadata, keyed by each device's modelId; mirrors on Cloudflare and Fastly back it up.

Crates

Crate	Role
`openlogi-core`	Types, TOML config, paths, and the button / action catalog; no HID, no async
`openlogi-hidpp`	Vendored HID++ protocol crate (lib name `hidpp`): channels, features, receivers
`openlogi-hid`	Device discovery, HID++ reads / writes, control capture, raw-HID lights
`openlogi-hook`	OS input hook: macOS CGEventTap, Linux evdev/uinput, Windows `WH_MOUSE_LL`
`openlogi-inject`	OS event synthesis: CGEvent, uinput / MPRIS, `SendInput`
`openlogi-camera`	UVC webcam discovery, capture, and image controls
`openlogi-assets`	Device-render registry schema and cached mirror fetches
`openlogi-agent-core`	Shared orchestration plus the agent ↔ GUI IPC contract
`openlogi-agent` / `openlogi-gui` / `openlogi-cli`	The three binaries

How a button press becomes an action

The control is captured: either by the OS hook (middle / back / forward) or diverted over HID++ 0x1b04 (gesture button, haptic panel, mode-shift, keyboard F-row) by a per-device capture session the agent rebuilds whenever bindings change.
The agent resolves the binding: the frontmost app's overlay first, then the device's global map.
The action runs: synthesized as OS input through openlogi-inject, written to the device over HID++ (DPI, SmartShift), or handled by the agent itself (the Actions Ring).

Configuration is a plain TOML file, read at startup and rewritten atomically on change; no cloud, no account. Values that live in volatile device RAM (DPI, SmartShift, Fn-lock, wheel resolution) are re-applied by the agent on every reconnect.

Developing without hardware

openlogi-agent-mock serves the real IPC contract from a scripted in-memory inventory, so the GUI can be developed with no Logitech device attached. See DEVELOPMENT.md.