Actions Ring

The Actions Ring is a radial launcher: press its trigger and eight actions fan out around the pointer, ready to pick. It is host-side UI — the agent renders the overlay and executes the chosen action — so any device with a spare button can open one, and the layout can change per application.

Opening and dismissing it

The trigger is the ShowActionsRing action. On an MX Master 4 the Haptic Sense Panel — the touch-sensitive thumb rest — carries it by default. To open the ring from a different control, bind ShowActionsRing to that button in config.toml: the GUI's action picker doesn't list it yet, so it is a config-file edit today.

The ring opens at the current cursor position, on the display the cursor is on. Click a slot — or hover it and release the trigger — to run its action. To leave without picking anything, press the trigger again, hit the × in the middle, or (on macOS) click anywhere outside the ring. An untouched ring expires on its own after a few seconds.

Slots

The eight positions are named clockwise from twelve o'clock: Top, TopRight, Right, BottomRight, Bottom, BottomLeft, Left, TopLeft. Out of the box they carry Cut, Copy, Paste, Browser Forward, Play/Pause, Browser Back, Undo, and Redo.

Each populated slot holds:

• An action — any binding action except ShowActionsRing itself (a ring cannot open another ring) and None (an empty slot is simply an absent entry, so clearing a slot removes it).
• An optional icon — pick from the built-in gallery, or leave it to inherit the action's own icon.
• An optional label — free text shown on hover. Custom labels render exactly as written and are never localized, which is what makes several RunShellCommand slots distinguishable instead of all reading "Run Command".

From the GUI

Select the device and open its Actions Ring tab: it appears for pointer devices with rebindable buttons, and for any device with a haptic panel. The editor shows the ring as it will appear, with a row of controls:

• Enabled — whether ShowActionsRing opens this device's ring at all.
• Haptic feedback — play device feedback when hovering and activating a slot, on hardware that supports it (HID++ 0x19b0 hapticFeedback). Off leaves the ring silent.
• Slot editor — click a slot to choose its action, its icon (Use action icon keeps the derived one), and a custom label; Clear slot empties it.

Per-application rings

A per-app ring is a complete layout, not a sparse overlay: when the frontmost app matches, that layout replaces the default one wholesale, so every slot you want has to be listed. This differs from per-app button bindings, where unlisted buttons fall through to the global map.

In the config

The ring lives under [devices.<key>.action_ring] in config.toml:

[devices."receiver:aabbccdd:slot:1".action_ring]
enabled = true
haptics = true

# Omit `icon` to use the action's own icon; omit `label` to use its name;
# omit a slot entirely to leave that position empty.
[devices."receiver:aabbccdd:slot:1".action_ring.default.slots]
Top = { action = "Cut" }
TopRight = { action = "Copy", icon = "Copy" }
Right = { action = "Paste", label = "Paste It" }
BottomRight = { action = "BrowserForward" }
Bottom = { action = "PlayPause" }
BottomLeft = { action = "BrowserBack" }
Left = { action = "Undo" }
TopLeft = { action = { OpenApplication = { path = "/Applications/Safari.app", display_name = "Safari" } } }

# A per-app ring is a complete layout, not an overlay.
[devices."receiver:aabbccdd:slot:1".action_ring.per_app."com.microsoft.VSCode".slots]
Top = { action = "Cut" }
TopRight = { action = "Copy" }
Right = { action = "Redo" }
BottomRight = { action = "NextTab" }
Bottom = { action = "ShowDesktop" }
BottomLeft = { action = "PrevTab" }
Left = { action = "Undo" }
TopLeft = { action = "Paste" }

Status: the ring overlay is rendered by the agent's GPUI helper on macOS, Linux, and Windows; dismiss-on-outside-click is macOS-only today. Haptic feedback needs a device that reports HID++ 0x19b0, such as the MX Master 4; every other device opens the ring silently. See 0x19b0 hapticFeedback for the protocol detail.