How to Configure the Actions Ring in OpenLogi: Slot Layout Guide

The Actions Ring is an eight-slot, cursor-centered overlay in OpenLogi that provides quick access to macros and system commands, configured via the action_ring table in your TOML config using slot0 through slot7 entries.

The Actions Ring is a central feature of the OpenLogi input management system, providing immediate contextual access to application launches, DPI changes, and custom macros. This radial menu appears at your cursor position when triggered and can be fully customized through configuration files or programmatic APIs. Understanding how to configure the Actions Ring slot layout allows you to optimize your workflow with up to eight context-aware actions per device or application.

Understanding the Actions Ring Architecture

The Actions Ring is invoked by the ShowActionsRing binding, defined in openlogi-core/src/binding/action.rs. When triggered, the system spawns a lightweight GPUI process (openlogi-overlay) that renders the ring around the current pointer location, communicating via the IPC layer (openlogi-ipc).

The implementation relies on several key components:

• Eight fixed slots: Arranged clockwise starting from the top (positions 0 through 7)
• Overlay renderer: openlogi-overlay/src/main.rs handles the visual presentation
• Haptic feedback: Managed by a coalescing haptic worker in openlogi-agent/src/server.rs
• Configuration storage: Per-device settings in openlogi-core/src/config/device.rs

Configuring the Actions Ring Slot Layout

OpenLogi stores ring configurations under the action_ring table within your device configuration file, typically located at ~/.config/openlogi/config.toml. According to the source code in docs/CONFIGURATION.md, you define layouts using a simple TOML structure.

Default Layout Structure

Define your default ring layout using the slot0 through slot7 keys under the [action_ring.default] table:

[device."<device-id>"]
actions_ring.enabled = true

[action_ring.default]
slot0 = { action = "ShowDesktop", icon = "desktop", label = "Desktop" }
slot1 = { action = "LaunchChrome", icon = "chrome", label = "Chrome" }
slot2 = { action = "MuteMic", icon = "mic", label = "Mute" }
slot3 = { action = "DoNothing", icon = "", label = "" }
slot4 = { action = "BrightnessUp", icon = "bright+", label = "Bright+" }
slot5 = { action = "BrightnessDown", icon = "bright-", label = "Bright-" }
slot6 = { action = "ShowNotifications", icon = "bell", label = "Notify" }
slot7 = { action = "OpenSettings", icon = "gear", label = "Settings" }

Per-Application Overrides

You can override the default slot layout for specific applications using the [action_ring."<bundle-id>"] syntax:

[action_ring."com.google.Chrome"]
slot0 = { action = "OpenNewTab", icon = "new-tab", label = "New Tab" }
slot1 = { action = "RefreshPage", icon = "refresh", label = "Refresh" }

Managing Empty Slots

To leave a slot empty, use the special DoNothing action as shown in slot3 above. This sentinel value is defined in openlogi-core/src/binding/action_ring.rs. The icon and label fields are optional but recommended for visual clarity; the set of available icons is defined in openlogi-core/src/binding/action_ring/icon.rs.

Practical Implementation Examples

Binding the Trigger

Map the ring to a physical button in your TOML configuration as defined in openlogi-core/src/binding/action.rs:

[[bindings]]
action = "ShowActionsRing"
trigger = "Button3"

Runtime Configuration with Rust

For dynamic updates, use the OpenLogi Rust API as implemented in openlogi-desktop/src/state/action_ring.rs:

use openlogi_core::config::DeviceConfig;
use openlogi_core::binding::action_ring::ActionRingSlot;

let mut cfg = DeviceConfig::load()?;

// Update slot 2 (third position clockwise from top)
cfg.action_ring.default[2] = ActionRingSlot::new(
    "RunMacro",
    Some("macro_icon".into()),
    Some("My Macro".into()),
);

cfg.save()?;

Reading Active Layouts at Runtime

Access the current runtime state from the agent side to inspect the active slot layout:

let ring_state = agent.runtime.actions_ring_state();
println!("Current layout: {:?}", ring_state.current_layout());

Summary

• The Actions Ring provides eight configurable slots (0-7) arranged clockwise from the top, rendered by the openlogi-overlay binary when triggered by the ShowActionsRing binding.
• Configure layouts in ~/.config/openlogi/config.toml under the [action_ring.default] table using slot0 through slot7 entries with action, icon, and label fields.
• Use per-application overrides with [action_ring."<bundle-id>"] syntax to customize layouts for specific apps, falling back to defaults when no override exists.
• Empty slots require the DoNothing action, defined in openlogi-core/src/binding/action_ring.rs.
• Changes are persisted to TOML and can be manipulated programmatically via the Rust API in openlogi-core/src/config/device.rs and openlogi-desktop/src/state/action_ring.rs.

Frequently Asked Questions

How many slots does the OpenLogi Actions Ring support?

The Actions Ring supports exactly eight slots, indexed 0 through 7. Slot 0 appears at the top of the ring, with subsequent slots arranged clockwise around the cursor. This fixed layout is defined in the core configuration schema in openlogi-core/src/config/device.rs and cannot be changed, though any slot can be left empty using the DoNothing action.

Can I have different Actions Ring layouts for different applications?

Yes. OpenLogi supports per-application overrides using the [action_ring."<bundle-id>"] syntax in your TOML configuration, as documented in docs/CONFIGURATION.md. When the active application changes, the system automatically switches to the corresponding layout, falling back to [action_ring.default] if no override exists for the current application.

What file handles the visual rendering of the Actions Ring?

The visual overlay is rendered by openlogi-overlay/src/main.rs, a separate GPUI process spawned by the agent. This process communicates with the main OpenLogi daemon via the IPC layer (openlogi-ipc/src/ipc.rs), receiving layout data and cursor position information to draw the ring at the correct screen coordinates.

How do I trigger the Actions Ring programmatically?

Invoke the ring by binding the ShowActionsRing action to a mouse button or key in your configuration file, or call it programmatically through the OpenLogi API. The binding definition resides in openlogi-core/src/binding/action.rs, and triggering it launches the overlay process managed by openlogi-agent/src/overlay.rs and activates the haptic feedback worker.

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