OpenLogi Development Workflow: Dev Agent, Mock Inventory, and Hot‑Reloading Explained

OpenLogi's development workflow combines a dev app bundle, mock agent with scripted hardware inventory, and automatic hot‑reloading to enable hardware‑free, fast‑iteration GUI development.

The AprilNEA/OpenLogi repository provides a sophisticated development environment for building Logitech device management software without requiring physical hardware. At the core of this system are three tightly coupled components: a temporary dev bundle, a mock agent that simulates complete device inventories, and a file‑watching hot‑reload mechanism that instantly reflects code changes in the running GUI.

The Dev App Bundle

When you launch OpenLogi via Cargo, the desktop runner creates a temporary platform‑specific application bundle using the openlogi-dev profile. As implemented in docs/DEVELOPMENT.md, this bundle performs automatic lifecycle management:

• Stops any previously started dev agent and overlay processes
• Starts fresh instances before the GUI launches
• Ensures the UI connects instantly to the correct IPC socket

This eliminates manual coordination between the desktop frontend and the agent backend. The dev bundle is the foundation that makes the rest of the workflow seamless.

The Mock Agent (openlogi-agent-mock)

The mock agent is a hardware‑free binary located at crates/openlogi-agent/src/bin/mock_agent.rs that implements the same tarpc Agent service interface as the production agent. It serves a scripted, deterministic inventory covering the full range of Logitech device types:

Simulated Device	Behavior
Bolt receiver	USB receiver for wireless peripherals
Online mouse	Connected and responsive
Offline mouse	Disconnected state handling
Lighting‑capable keyboard	RGB/backlight control
Standalone Litra light	Elgato‑style camera lighting
Rotating foreground apps	Simulates camera_active flag flipping every 30 seconds

Because the mock defaults to the dev profile, it communicates over the dev socket without interfering with any production OpenLogi installation. Writes to DPI, SmartShift, and lighting settings persist in memory, enabling realistic testing of configuration flows.

Environment Variables for Mock Control

# Use production socket (test against real production GUI)

OPENLOGI_PROFILE=prod cargo run -p openlogi-agent --bin openlogi-agent-mock

# Allow coexistence with an already‑running real agent

OPENLOGI_ALLOW_EXTERNAL_AGENT=1 cargo run -p openlogi-agent --bin openlogi-agent-mock

Hot‑Reloading and Watch‑Based Restarts

The dev runner implements automatic process lifecycle management based on file watching. According to docs/DEVELOPMENT.md and crates/openlogi-agent-core/src/watchers/poll.rs:

1. The runner watches the built agent and overlay binaries
2. When you rebuild after code changes, it kills the old agent process
3. Launches the new binary automatically
4. The desktop process reconnects to the refreshed IPC socket

This creates a live‑code feedback loop without manually restarting the GUI. The same mechanism applies to the overlay binary, enabling simultaneous iteration on multiple components.

Step‑by‑Step Development Session

Follow these commands to start a fresh development session:

1. Build and run the dev GUI

# Using devenv (recommended)

devenv tasks run openlogi:gui

# Fallback using Cargo directly

cargo run -p openlogi-desktop

This creates the dev bundle, stops stale processes, and waits for the dev agent socket.

2. Start the mock agent

cargo run -p openlogi-agent --bin openlogi-agent-mock

Spins up the hardware‑free agent with full device inventory.

3. (Optional) Prevent automatic agent spawning

OPENLOGI_DEV_AGENT=0 cargo run -p openlogi-desktop

Use when you already have a mock running and want to avoid rebuilding the embedded agent.

4. Hot‑reload workflow

Edit source files → run cargo check or cargo run → the dev runner automatically restarts the agent → GUI reconnects instantly.

What You Can Develop Without Hardware

The mock agent enables complete feature development:

• UI components — Actions Ring, component gallery, settings panels
• DPI and SmartShift — write persistence and slider interactions
• Lighting control — RGB synchronization and effects
• Camera‑linked behaviors — automatic camera_active flag testing
• Bolt pairing flows — discovery, passkey entry, device addition

The mock's 30‑second camera_active rotation specifically supports testing foreground‑app detection and lighting automation.

Key Source Files

Understanding these files clarifies how the development workflow operates:

File	Purpose
docs/DEVELOPMENT.md	Overall workflow documentation, dev bundle behavior, hot‑reloading configuration
crates/openlogi-agent/src/bin/mock_agent.rs	Mock agent implementation and scripted inventory definition
crates/openlogi-desktop/src/lib.rs	Desktop client connection logic for dev agent socket
crates/openlogi-agent-core/src/watchers/poll.rs	File watcher implementation triggering hot‑reload
xtask/src/main.rs	devenv task definitions (openlogi:gui, openlogi:check)

Summary

• The dev app bundle (openlogi-dev profile) automates process lifecycle management, ensuring clean agent/overlay startup
• The mock agent provides deterministic hardware simulation across mice, keyboards, receivers, and lighting devices without physical Logitech peripherals
• Hot‑reloading via file watching eliminates manual restart cycles, with automatic agent termination and socket reconnection
• Environment variables OPENLOGI_PROFILE and OPENLOGI_ALLOW_EXTERNAL_AGENT control socket selection and process coexistence
• The complete workflow enables hardware‑free development of DPI controls, SmartShift, lighting automation, and Bolt pairing flows

Frequently Asked Questions

How do I prevent the dev GUI from automatically spawning its own agent?

Set OPENLOGI_DEV_AGENT=0 when running the desktop: OPENLOGI_DEV_AGENT=0 cargo run -p openlogi-desktop. This is useful when you want the GUI to connect to an already‑running mock agent rather than rebuilding and embedding a fresh agent binary.

Can the mock agent simulate camera‑activated lighting behavior?

Yes. The mock flips a camera_active flag every 30 seconds on a rotating list of foreground applications. This triggers the same lighting automation logic that physical Litra devices would respond to, enabling testing of camera‑linked effects without actual video software running.

What happens to configuration changes made to the mock agent?

All writes persist in memory for the duration of the mock process. DPI adjustments, SmartShift toggles, and lighting settings are retained and reflected in subsequent API calls, providing realistic state management for development and testing.

How does hot‑reloading work when I modify agent code?

The dev runner watches the built binary via crates/openlogi-agent-core/src/watchers/poll.rs. When Cargo produces a new binary, the runner kills the old agent process, launches the new one, and the desktop GUI automatically reconnects to the refreshed IPC socket—typically completing within seconds.

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