How to Configure the Actions Ring in OpenLogi: TOML and GUI Setup

To configure the Actions Ring in OpenLogi, edit the device-specific actions_ring section in config.toml to define eight radial slots with specific actions, icons, and labels, then reload the configuration or use the openlogi-desktop GUI editor for live changes.

OpenLogi implements the Actions Ring as a customizable eight-slot radial menu that provides quick access to system commands and applications. The configuration resides in the TOML-based user configuration file and supports per-device customization using unique device_key identifiers. Whether you prefer editing configuration files directly or using the graphical interface, OpenLogi offers flexible methods to tailor the ring to your workflow.

Understanding the Actions Ring Structure

The Actions Ring is defined within device-specific blocks in the OpenLogi configuration. Each device entry identified by its device_key (such as "Logitech G502") contains an actions_ring table that controls visibility and slot assignments.

Configuration File Location

User settings are stored in config.toml at the root of the OpenLogi configuration directory. The parser in crates/openlogi-core/src/config.rs handles deserialization into the DeviceConfig structure, which contains the ActionsRing struct defining the eight-slot layout.

The Eight-Slot Layout

Each device supports exactly eight slots arranged clockwise from the top position. The slots array must contain eight entries, where each entry specifies an action binding and optional visual customization through icon or label fields.

TOML Configuration Syntax

Configuring the ring requires editing the TOML file under the [device."<device_key>"] section. Three primary settings control the ring behavior.

Enabling the Ring

Set actions_ring.enabled to true or false to toggle visibility for the specific device. The default value is true.

Defining Slot Actions

Each slot entry requires an action field referencing predefined constants from crates/openlogi-core/src/binding/action_ring.rs. Valid options include ShowActionsRing, OpenApplication, and DoNothing. Optional fields icon and label override default glyphs with custom graphics or text labels.

[device."Logitech G502"]

# Enable the Actions Ring for this device

actions_ring.enabled = true

# Customize the eight slots (clockwise from the top)

[[device."Logitech G502".actions_ring.slots]]
action = "ShowActionsRing"      # Slot 1 – the default “show ring” action

icon   = "grid"                # Use the grid icon for this slot

[[device."Logitech G502".actions_ring.slots]]
action = "OpenApplication"
label  = "Chrome"              # Show a literal label instead of an icon

[[device."Logitech G502".actions_ring.slots]]
action = "DoNothing"           # Empty slot – nothing happens

# … repeat for the remaining five slots …

Available Actions and Validation

The permissible action set is defined in crates/openlogi-core/src/binding/action_ring.rs. This module validates slot assignments during configuration loading, rejecting illegal combinations such as nesting ShowActionsRing inside the ring itself.

Common actions include:

• ShowActionsRing: Recursively opens the ring menu (typically reserved for the top slot)
• OpenApplication: Launches a specified program when combined with metadata
• DoNothing: Creates an empty slot that performs no action

Runtime Architecture

After configuration parsing, three core components handle the Actions Ring lifecycle.

Configuration Parsing

The Config::load method in crates/openlogi-core/src/config.rs deserializes the TOML file and instantiates DeviceConfig structures containing the ActionsRing data.

State Management

crates/openlogi-agent-core/src/action_ring.rs maintains the current session state and exposes RPC endpoints for showing or hiding the ring. The ActionRingClient provides async methods to trigger these state changes via the IPC layer in crates/openlogi-ipc/src/ipc.rs.

Overlay Rendering

The GPUI-based overlay in crates/openlogi-overlay/src/main.rs queries the agent's state to render the radial menu on screen.

GUI Configuration Method

The openlogi-desktop application provides an Actions Ring editor accessible under the Actions Ring tab. This interface allows live editing without manually modifying config.toml. Changes made through the GUI persist automatically to the configuration file and apply immediately to the running agent.

Code Examples

Reading the configuration programmatically:

use openlogi_core::config::Config;
use std::path::Path;

fn load_device_config(path: &Path, device_key: &str) {
    let cfg = Config::load(path).expect("could not load config");
    let dev_cfg = cfg.device(device_key).expect("device not found");
    println!("Actions Ring enabled: {}", dev_cfg.actions_ring.enabled);
    for (i, slot) in dev_cfg.actions_ring.slots.iter().enumerate() {
        println!("Slot {} → {:?}", i + 1, slot);
    }
}

Triggering the ring via IPC:

use openlogi_agent_core::action_ring::ActionRingClient;
use openlogi_ipc::ipc::ShowActionsRingRequest;

async fn show_ring(client: ActionRingClient) -> anyhow::Result<()> {
    client.show_ring(ShowActionsRingRequest {}).await?;
    Ok(())
}

Summary

• The Actions Ring is an eight-slot radial menu configured per device in config.toml
• Each device block uses a device_key identifier and contains actions_ring.enabled and actions_ring.slots settings
• Slots accept actions defined in crates/openlogi-core/src/binding/action_ring.rs with optional icon or label overrides
• Configuration changes require reloading the agent or using the openlogi-desktop GUI editor
• Runtime components in openlogi-agent-core and openlogi-overlay handle state management and rendering

Frequently Asked Questions

Can I have different Actions Ring configurations for different mice?

Yes. OpenLogi supports per-device configuration using unique device_key identifiers in the TOML file. Each [device."<device_key>"] block can contain independent actions_ring settings, allowing distinct layouts for different hardware models.

What happens if I assign ShowActionsRing to a slot inside the ring?

The configuration validator in crates/openlogi-core/src/binding/action_ring.rs rejects this assignment during parsing. This prevents infinite recursion where triggering the ring would attempt to reopen itself.

Do I need to restart OpenLogi after editing config.toml?

Yes, you must reload the configuration or restart the OpenLogi agent to apply TOML changes. Alternatively, use the openlogi-desktop GUI editor, which applies changes immediately and persists them to the configuration file.

How do I create an empty slot in the Actions Ring?

Set the slot's action field to "DoNothing". This creates a placeholder that renders no functionality when selected, effectively creating a gap in the radial menu.

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