AprilNEA/OpenLogi instruction manual

1. Purpose, scope, and Claude Code classification

OpenLogi instruction manual

OpenLogi is a native, local-first Rust/GPUI application for controlling supported Logitech mice, keyboards, webcams, and Litra lights. It communicates with input devices through HID++ and with webcams through UVC. It provides a GUI, a background agent that owns device I/O, and a scriptable CLI. Devices may connect through Logi Bolt or Unifying receivers, Bluetooth, or a wired connection; OpenLogi reports battery percentage and charging state where available.

**Claude Code classification: unclassified.** The supplied first-party files document a standalone hardware-control application and its development libraries, not a Claude Code plugin, skill, hook, MCP server, or integration. There is therefore no source-supported Claude Code installation or interaction mechanism to classify. OpenLogi can exist on the same computer as Claude Code, but the documentation establishes no relationship between them.

The project is under active development and is explicitly described as not yet stable. Features and TOML configuration may change. OpenLogi is available for macOS, Linux, and Windows, but some functions vary by platform or hardware. Before starting it, quit **Logi Options+**: both programs compete for HID++ access, and only one can own a receiver at a time. OpenLogi is not affiliated with Logitech.

This manual covers only behavior present in the supplied files. The referenced full configuration and development guides were not supplied, so this manual does not invent TOML keys, build procedures, or CLI options beyond those directly documented.

2. Install and start OpenLogi on macOS, Linux, or Windows

macOS

macOS 13 or later is required. Either download the signed and notarized DMG from the repository’s latest release and drag `OpenLogi.app` into `/Applications`, or use the official Homebrew cask:

brew install --cask openlogi

To follow the newest GitHub release through the project-maintained tap instead, use:

brew tap aprilnea/tap
brew install --cask aprilnea/tap/openlogi@latest

Install either `openlogi` or `openlogi@latest`, never both. The latter may update before the official cask’s automatic update.

Linux

Prebuilt packages support `x86_64`/`amd64` and `arm64`/`aarch64` and require GLIBC 2.35 or newer. Download the appropriate release artifact, then run only the matching documented command:

# Debian / Ubuntu
sudo dpkg -i openlogi_*.deb

# Fedora / RHEL
sudo rpm -i openlogi-*.rpm

# Arch Linux
sudo pacman -U openlogi-*.pkg.tar.zst

Packages install udev rules granting the user access to `/dev/hidraw*`, `/dev/uinput`, and the relevant `/dev/input/event*` node. After package installation, enable the per-user agent:

systemctl --user enable --now openlogi-agent.service

The supplied README also documents a NixOS module: add the `AprilNEA/OpenLogi` flake input, include `openlogi.nixosModules.default`, and set `programs.openlogi.enable = true`. That module installs the package and udev rules and starts the agent with the graphical session.

Windows

Each release provides signed portable ZIP and per-user MSI packages for x86_64 and arm64. Both contain `OpenLogi.exe` and `openlogi-agent.exe`. With the portable ZIP, keep these files side by side because the GUI connects to the agent for all device I/O. The agent supplies a tray icon with **Show Main Window** and **Quit**. Windows support is documented as validated on Windows 11; it is newer than the macOS build.

3. Device management, remapping, profiles, and Litra lights

OpenLogi inventories connected and paired devices and displays their connection state, type, codename, receiver slot, battery percentage, and charge state where those values are available. Its HID layer handles device enumeration, receiver routing, shared-channel transport, pairing-receiver listing, pairing, and unpairing. Hardware capabilities differ, so a control appears or works only when the device exposes the corresponding HID++ feature.

Button remapping uses an operating-system input hook. You can assign items from the built-in action catalog and define custom keyboard shortcuts in the plain-text TOML configuration. The English README additionally documents independent short-press and long-press actions, plus chords held until button release for uses such as push-to-talk. Media-key actions use D-Bus MPRIS on Linux. Some macOS-only actions have no universal Linux equivalent and become no-ops there; Windows maps platform actions to native equivalents when available.

Per-application profile overlays automatically switch when application focus changes. This works on macOS and Windows and on Linux under X11 or XWayland. Native GNOME Wayland requires the separately documented extension described later in this manual. Because all configuration is stored in one TOML file, it can be synchronized between machines by a method of your choosing, but no synchronization command is documented.

For Logitech Litra lights, OpenLogi controls power, brightness, and color temperature. Optional automatic power follows camera activity. These are hardware-control functions, so availability depends on a detected compatible light.

On Windows, the background agent normally keeps a tray icon visible. To suppress it, place this documented setting in the TOML `[app_settings]` block and restart the agent:

[app_settings]
show_in_menu_bar = false

The GUI toggle for this setting is currently documented as macOS-only.

4. Mouse and keyboard functions

Mouse controls

OpenLogi can capture and remap the middle button on all supported platforms. It can also capture mode-shift and thumbwheel buttons when the particular device exposes them. Any capable physical button may receive the gesture role, or gestures may be disabled completely. Gesture bindings are assigned independently by direction and support live capture.

The **Actions Ring** is a cursor-centered overlay containing eight action slots. Assign the documented `ShowActionsRing` action to invoke it. Ring layouts may vary by application through profile overlays.

DPI control uses HID++ feature `0x2201`. OpenLogi supports DPI presets and actions that either cycle presets or select a particular preset. Its HID API exposes typed `get_dpi` and `set_dpi` operations for supported hardware. SmartShift uses feature `0x2111` and provides wheel-mode switching, sensitivity control, and a permanent-ratchet panel; the HID layer includes SmartShift helpers. High-resolution-wheel and thumbwheel helpers are also documented. Per-device native scroll inversion uses feature `0x2121` where the mouse supports it.

Reprogrammable-control helpers configure supported HID++ controls. Diagnostic APIs can dump those controls and their capability flags. At protocol level, the vendored HID++ library includes typed pointer and wheel wrappers for MousePointer, AdjustableDpi, ExtendedAdjustableDpi, VerticalScrolling, HiResWheel, Thumbwheel, SmartShift, and enhanced SmartShift.

Keyboard controls

On macOS and Windows, F keys can be remapped globally using the same action catalog as mouse buttons. Additional keyboard actions include typing text, sending key combinations, and running multistep workflows. Supported keyboards can use static RGB lighting through HID++ `ColorLedEffects` (`0x8070`) or `PerKeyLighting` (`0x8080`). The HID layer’s `set_keyboard_color` and `set_keyboard_color_with` functions prefer the typed `ColorLedEffects` route and fall back to the per-key-lighting stream. Protocol wrappers also cover backlight, illumination, brightness, RGB effects, Fn inversion, disabled keys, usage-based disabled keys, and keyboard mode status.

5. Webcam controls, persistence, privacy behavior, and profiles

OpenLogi documents plug-and-play support for Logitech UVC webcams, including Brio, StreamCam, and C920-series devices. The live preview opens the camera only while the preview is being viewed. Leaving that view releases the camera completely and turns off its activity LED, rather than retaining the camera merely to keep the application ready.

Image controls are written directly to UVC hardware. Documented controls are zoom, focus, exposure, brightness, contrast, saturation, sharpness, white balance, tint, anti-flicker, and low-light compensation. Focus, exposure, and white balance include automatic-mode toggles. Because values are applied at the camera, changes carry into Meet, Zoom, OBS, and other applications that subsequently use the same device, subject to the camera supporting the selected UVC control.

OpenLogi includes one-click **Default**, **Streaming**, and **Video call** profiles. You can also save custom snapshots. Settings persist separately for each camera and are written back to that camera’s hardware the next time its view is opened. The supplied files do not document exact GUI button labels for creating, renaming, deleting, importing, or exporting custom snapshots, so no additional procedure should be inferred.

The project describes itself as local-first and says it requires no account or telemetry. Its webcam preview behavior also minimizes how long OpenLogi itself holds the camera. Asset rendering is a separate networked function: the CLI’s asset synchronization contacts documented mirrors unless a uniform asset origin is selected. Nothing in the supplied files says that webcam images are uploaded.

OpenLogi also integrates camera activity with compatible Litra lights: when optional auto power is enabled, the light’s power follows camera activity. This is distinct from webcam image adjustment and requires a detected compatible Litra device.

6. Command-line reference and diagnostics

The installed CLI executable is `openlogi`. Running it without a subcommand defaults to the device list. The complete supplied usage summary is:

openlogi list                 # paired devices: slot, codename, kind, online, battery
openlogi assets sync          # pre-fetch device renders from the fastest available mirror
openlogi diag features        # dump every HID++ feature the active device reports
openlogi diag controls        # dump reprogrammable controls and capability flags
openlogi diag dpi             # read → write → read-back → restore DPI (smoke test)
openlogi diag smartshift      # toggle SmartShift and restore (smoke test)
openlogi diag lighting ff0000 # solid colour for a wired RGB keyboard (any RRGGBB hex)

`list` provides a one-shot inventory of paired devices. `assets sync` pre-fetches device render assets. During automatic selection, it probes `assets.openlogi.org`, the versioned Cloudflare Pages release alias, and the pinned jsDelivr npm release concurrently. The first endpoint returning a valid catalog becomes the source for every file in that synchronization run. To select one uniform origin, set `OPENLOGI_ASSETS` or use the documented option:

openlogi assets sync --base <URL>

`diag features` reports every HID++ feature advertised by the active device. `diag controls` reports reprogrammable controls and their capability flags. `diag dpi` is a reversible smoke test: it reads the current DPI, writes a value, reads it back, and restores the original. `diag smartshift` similarly toggles SmartShift and restores it. `diag lighting` applies one solid `RRGGBB` hexadecimal color to a wired RGB keyboard; `ff0000` is the documented red example.

For verbose tracing in the CLI, GUI, or agent, set the documented environment variable before launching the relevant process:

OPENLOGI_LOG=debug openlogi list

Diagnostics can temporarily change hardware state even when they restore it, so use them on the intended active device.

7. GNOME Wayland support and documented Linux source installation

GNOME’s Mutter compositor does not expose the focused window to ordinary Wayland clients through the mechanisms OpenLogi would otherwise use. The supplied GNOME Shell extension bridges that gap for per-application mouse profiles. It reads only the focused window’s WM_CLASS—no title, window contents, input, or UI—and exports it over the session D-Bus as `org.openlogi.Frontmost` at `/org/openlogi/Frontmost`. `GetFocusedWmClass()` returns a string, empty when nothing is focused; `FocusedWmClassChanged(s)` fires on each native focus change.

From the extension directory, install the two documented files locally:

UUID=openlogi-frontmost@openlogi.dev
DEST="$HOME/.local/share/gnome-shell/extensions/$UUID"
mkdir -p "$DEST"
cp metadata.json extension.js "$DEST"/

On Wayland, log out and back in, then enable and inspect it:

gnome-extensions enable "$UUID"
gnome-extensions info "$UUID"   # State should be ACTIVE

Verification commands are:

busctl --user introspect org.openlogi.Frontmost /org/openlogi/Frontmost
gdbus call --session -d org.openlogi.Frontmost -o /org/openlogi/Frontmost -m org.openlogi.Frontmost.GetFocusedWmClass
gdbus monitor --session -d org.openlogi.Frontmost -o /org/openlogi/Frontmost

A WM_CLASS result and focus-change signals show that the backend can discover it when the hook next starts. The metadata covers GNOME 45–50; newer releases may require metadata changes.

For the supplied Linux install script, first create all four required release binaries exactly as its error guidance states:

cargo build --release -p openlogi -p openlogi-desktop -p openlogi-overlay -p openlogi-agent

Then the script’s documented forms are `./install.sh [--prefix PREFIX]` and `./install.sh --help`; its default prefix is `/usr/local`. It installs the CLI, desktop GUI, overlay, agent, udev rules, optional systemd user unit, desktop entry, and icons. Afterward, start `openlogi-desktop` or enable the user agent with the earlier `systemctl` command.

8. Developer xtask, public Rust layers, limitations, and licensing

Repository development orchestration is exposed through `xtask`, run from the repository root in either documented form:

devenv shell -- cargo xtask <command>
# or, without the cargo alias:
devenv shell -- cargo run -p xtask -- <command>

`ci [--list] [--dry-run] [JOB…]` reproduces host-compatible `ci.yml` jobs and skips incompatible jobs with a reason. `macos icon` compiles the Icon Composer document. `macos bundle [--channel dev|production]` builds the app and embeds agent and overlay helpers; it defaults to a separately identified dev bundle. `macos dev-bundle --binary <path>` wraps a freshly built desktop binary and is documented as Cargo-runner-driven, not a hand-run task. `macos dmg` packages an existing production app; `macos package` builds, optionally signs, and creates the DMG, accepting `--target aarch64-apple-darwin` or `--target x86_64-apple-darwin`. `linux package` creates DEB, RPM, and Arch artifacts through nfpm.

Release commands are `release changelog`, which writes the next workspace-version section using git-cliff; `release check-publish`, which validates a publishable, versioned crates.io dependency closure; `release checkout-version-bump`, which selects the commit introducing the current workspace version; and `release latest-json`, which generates the stable updater manifest.

The `openlogi-hid` crate supplies discovery, routing, pairing (`list_pairing_receivers`, `run_pairing`, `unpair`), enumeration, DPI, wheel, SmartShift, thumbwheel, reprogrammable-control, keyboard-color, and diagnostic helpers. The lower-level vendored `openlogi-hidpp` crate provides typed HID++ wrappers for device/power, hosts/platforms, pointer/wheel, remapping, keyboard, lighting, audio, report-rate, crown, touch, and solar-keyboard features. Unknown wire values return `Hidpp20Error::UnsupportedResponse` rather than being guessed.

Important limits: the project is unstable; behavior depends on OS, display server, and device capabilities; Windows support is newer; prebuilt Linux packages require GLIBC 2.35+. Code is dual-licensed under Apache-2.0 or MIT, while the vendored HID++ fork is 0BSD. OpenLogi’s name, logo, icon, and `design/` brand assets are not covered by those code licenses and require separate permission for use in forks or distributions.